nuxt-api-contract 0.1.0

package/dist/server.mjs

@@ -0,0 +1,94 @@
+import { a as getContractMock } from './shared/nuxt-api-contract.QDGSGaVY.mjs';
+export { b as buildRequestPath, c as clearContractRegistry, d as defineApiContract, g as getContractByName, i as isApiContract, l as listRegisteredContracts, m as mockContract, r as registerContract, s as serializeQuery, e as serializeQueryValue, f as stableStringify } from './shared/nuxt-api-contract.QDGSGaVY.mjs';
+import { A as ApiError, s as serializeApiError, B as BUILT_IN_ERROR_CODES } from './shared/nuxt-api-contract.obS6uV8A.mjs';
+export { c as createApiError, i as isApiError, p as parseApiErrorPayload, t as toApiError } from './shared/nuxt-api-contract.obS6uV8A.mjs';
+export { f as formatValidationMessage, s as sanitizeIssues, t as toValidationIssues } from './shared/nuxt-api-contract.DCAU2j7t.mjs';
+import { defineEventHandler, getRequestHeaders, getQuery, readValidatedBody, setResponseStatus } from 'h3';
+import { v as validateContractInput, r as readRuntimeConfig, s as shouldValidateResponse, a as validateContractResponse } from './shared/nuxt-api-contract.DDpgZj2g.mjs';
+export { b as rawQuerySchema } from './shared/nuxt-api-contract.DDpgZj2g.mjs';
+import 'zod';
+
+const CONTRACT_HANDLER_META = Symbol.for("nuxt-api-contract.contractHandlerMeta");
+function defineContractHandler(contract, handler) {
+  const eventHandler = defineEventHandler(async (event) => {
+    try {
+      let headers;
+      if (contract.headers) {
+        const raw = {};
+        for (const [key, value] of Object.entries(getRequestHeaders(event))) {
+          if (typeof value === "string") raw[key] = value;
+        }
+        headers = validateContractInput(contract, "headers", contract.headers, raw);
+      } else {
+        headers = getRequestHeaders(event);
+      }
+      let params;
+      if (contract.params) {
+        const routeParams = event.context.params ?? {};
+        params = validateContractInput(contract, "params", contract.params, routeParams);
+      } else {
+        params = event.context.params ?? {};
+      }
+      let query;
+      if (contract.query) {
+        query = validateContractInput(contract, "query", contract.query, getQuery(event));
+      } else {
+        query = getQuery(event);
+      }
+      let body;
+      if (contract.body) {
+        const rawBody = await readValidatedBody(event, (value) => value);
+        body = validateContractInput(contract, "body", contract.body, rawBody);
+      } else if (contract.method !== "GET" && contract.method !== "HEAD") {
+        body = await readValidatedBody(event, (value) => value);
+      } else {
+        body = void 0;
+      }
+      const ctx = {
+        params,
+        query,
+        body,
+        headers,
+        event
+      };
+      const runtimeConfig = readRuntimeConfig(() => useNitroRuntimeConfig(event));
+      const mock = getContractMock(contract);
+      if (runtimeConfig.mocks && mock?.response) {
+        const mocked = await mock.response();
+        return finalize(contract, mocked, runtimeConfig);
+      }
+      const result = await handler(ctx);
+      return finalize(contract, result, runtimeConfig);
+    } catch (error) {
+      return respondWithError(event, error);
+    }
+  });
+  const withMeta = eventHandler;
+  withMeta[CONTRACT_HANDLER_META] = { contract, handler };
+  return eventHandler;
+}
+function useNitroRuntimeConfig(event) {
+  const ctx = event.context;
+  return ctx.nitro?.runtimeConfig ?? ctx._nitro?.runtimeConfig ?? ctx.$config;
+}
+function finalize(contract, result, runtimeConfig) {
+  if (contract.response && shouldValidateResponse(runtimeConfig.validateResponse)) {
+    return validateContractResponse(contract, contract.response, result);
+  }
+  return result;
+}
+function respondWithError(event, error) {
+  if (error instanceof ApiError) {
+    setResponseStatus(event, error.statusCode, error.code);
+    return serializeApiError(error);
+  }
+  setResponseStatus(event, 500, BUILT_IN_ERROR_CODES.internal);
+  return {
+    error: {
+      code: BUILT_IN_ERROR_CODES.internal,
+      message: "Internal server error"
+    }
+  };
+}
+
+export { ApiError, BUILT_IN_ERROR_CODES, defineContractHandler, getContractMock, readRuntimeConfig, serializeApiError, shouldValidateResponse, validateContractInput, validateContractResponse };

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

@@ -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.mjs';
+
+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.CPm9WbWA.d.mts

@@ -0,0 +1,165 @@
+import { ZodType } from 'zod';
+
+/**
+ * Marker used to identify contract objects at runtime (and in the registry).
+ */
+declare const API_CONTRACT_KIND: "api-contract";
+/**
+ * Supported HTTP methods.
+ */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+/**
+ * Splits a string path into its segments at the type level.
+ * `/api/users/:id` -> ['api', 'users', ':id']
+ */
+type SplitPath<TPath extends string> = TPath extends `${infer Head}/${infer Tail}` ? [...SplitPath<Head>, ...SplitPath<Tail>] : TPath extends '' ? [] : [TPath];
+/**
+ * Extracts the path parameter object from a path string.
+ * `/api/posts/:postId/comments/:commentId` -> { postId: string, commentId: string }
+ */
+type PathParams<TPath extends string> = {
+    [Segment in SplitPath<TPath>[number] as Segment extends `:${infer Name}` ? Name : never]: string;
+};
+interface AuthConfig {
+    required?: boolean;
+    roles?: readonly string[];
+    [key: string]: unknown;
+}
+/**
+ * The input accepted by `defineApiContract()`. All schema fields are optional;
+ * generics capture the literal types the user provided.
+ */
+interface ApiContractDefinition<TMethod extends HttpMethod = HttpMethod, TPath extends string = string, TParams extends ZodType | undefined = ZodType | undefined, TQuery extends ZodType | undefined = ZodType | undefined, TBody extends ZodType | undefined = ZodType | undefined, THeaders extends ZodType | undefined = ZodType | undefined, TResponse extends ZodType | undefined = ZodType | undefined> {
+    /** Unique contract name, used by the registry / DevTools / OpenAPI. */
+    name?: string;
+    /** Optional contract version (see roadmap: contract versioning). */
+    version?: number;
+    method: TMethod;
+    path: TPath;
+    /** Path parameters schema, e.g. `z.object({ id: z.string().uuid() })`. */
+    params?: TParams;
+    /** Query parameters schema. */
+    query?: TQuery;
+    /** Request body schema. */
+    body?: TBody;
+    /** Request headers schema (validated against raw header values). */
+    headers?: THeaders;
+    /** Successful response schema. */
+    response?: TResponse;
+    /** Known error payloads keyed by machine-readable error code. */
+    errors?: Record<string, ZodType>;
+    /** OpenAPI summary. */
+    summary?: string;
+    /** OpenAPI description. */
+    description?: string;
+    /** OpenAPI tags. */
+    tags?: readonly string[];
+    /** Marks the endpoint as requiring authentication (informational / extension point). */
+    auth?: boolean | AuthConfig;
+    /** Free-form metadata consumed by tooling (DevTools, mocks, docs). */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A frozen, type-safe API contract — the single source of truth for
+ * runtime validation, TypeScript types, OpenAPI, DevTools and mocks.
+ */
+interface ApiContract<TMethod extends HttpMethod = HttpMethod, TPath extends string = string, TParams extends ZodType | undefined = ZodType | undefined, TQuery extends ZodType | undefined = ZodType | undefined, TBody extends ZodType | undefined = ZodType | undefined, THeaders extends ZodType | undefined = ZodType | undefined, TResponse extends ZodType | undefined = ZodType | undefined> {
+    readonly kind: typeof API_CONTRACT_KIND;
+    readonly method: TMethod;
+    readonly path: TPath;
+    readonly name: string | undefined;
+    readonly version: number | undefined;
+    readonly params: TParams;
+    readonly query: TQuery;
+    readonly body: TBody;
+    readonly headers: THeaders;
+    readonly response: TResponse;
+    readonly errors: Readonly<Record<string, ZodType>> | undefined;
+    readonly summary: string | undefined;
+    readonly description: string | undefined;
+    readonly tags: readonly string[] | undefined;
+    readonly auth: boolean | AuthConfig | undefined;
+    readonly metadata: Readonly<Record<string, unknown>> | undefined;
+}
+/**
+ * Extracts a definition property, defaulting to `undefined` when the key is
+ * absent from the captured (const-inferred) literal type.
+ */
+type PickDefKey<TDef, TKey extends 'params' | 'query' | 'body' | 'headers' | 'response'> = TKey extends keyof TDef ? TDef[TKey] : undefined;
+/**
+ * Maps a definition literal into the resolved contract type.
+ */
+type ContractFromDefinition<TDef extends ApiContractDefinition> = ApiContract<TDef['method'], TDef['path'], PickDefKey<TDef, 'params'>, PickDefKey<TDef, 'query'>, PickDefKey<TDef, 'body'>, PickDefKey<TDef, 'headers'>, PickDefKey<TDef, 'response'>>;
+/**
+ * Input type produced by a Zod schema, or an empty object when absent.
+ */
+type ExtractSchemaInput<T> = T extends ZodType<any, any, infer Input> ? Input : Record<never, never>;
+/**
+ * Any contract, with all generics widened. Used as a variance-friendly bound.
+ */
+type AnyApiContract = ApiContract<HttpMethod, string, ZodType | undefined, ZodType | undefined, ZodType | undefined, ZodType | undefined, ZodType | undefined>;
+type ContractPathParams<C extends AnyApiContract> = C extends {
+    path: infer TPath extends string;
+} ? PathParams<TPath> : Record<never, never>;
+/**
+ * The params the client must send: the intersection of the params schema
+ * input and the parameters extracted from the path itself.
+ */
+type ContractParamsInput<C extends AnyApiContract> = ExtractSchemaInput<C['params']> & ContractPathParams<C>;
+type ContractQueryInput<C extends AnyApiContract> = ExtractSchemaInput<C['query']>;
+type ContractBodyInput<C extends AnyApiContract> = ExtractSchemaInput<C['body']>;
+type ContractHeadersInput<C extends AnyApiContract> = ExtractSchemaInput<C['headers']>;
+/** Response type as returned by handlers (Zod input side). */
+type ContractHandlerResponse<C extends AnyApiContract> = ExtractSchemaInput<C['response']>;
+/** Response type as received by the client (Zod output side). */
+type ContractClientResponse<C extends AnyApiContract> = ExtractSchemaOutput<C['response']>;
+/** Known error codes declared on the contract, plus built-in codes. */
+type ContractErrorCode<C extends AnyApiContract> = (C extends {
+    errors: infer TErrors;
+} ? keyof TErrors & string : never) | 'VALIDATION_ERROR' | 'API_CONTRACT_RESPONSE_VALIDATION_ERROR' | 'INTERNAL_ERROR';
+type MaybePromise<T> = T | Promise<T>;
+type EmptyObject = Record<never, never>;
+type IsEmptyObject<T> = keyof T extends never ? true : false;
+/**
+ * Request options accepted by `useApi` / `useApiClient`.
+ * Requiredness of `params` / `query` / `body` / `headers` is derived from the
+ * contract: an option is required when its schema (or the path) demands it,
+ * and optional (or rejected) otherwise.
+ */
+type ApiRequestOptions<C extends AnyApiContract> = (IsEmptyObject<ContractParamsInput<C>> extends true ? {
+    params?: ContractParamsInput<C>;
+} : {
+    params: ContractParamsInput<C>;
+}) & (undefined extends C['query'] ? {
+    query?: ContractQueryInput<C>;
+} : {
+    query: ContractQueryInput<C>;
+}) & (undefined extends C['body'] ? {
+    body?: ContractBodyInput<C>;
+} : {
+    body: ContractBodyInput<C>;
+}) & (undefined extends C['headers'] ? {
+    headers?: ContractHeadersInput<C>;
+} : {
+    headers: ContractHeadersInput<C>;
+}) & {
+    /** Abort signal forwarded to the underlying fetch. */
+    signal?: AbortSignal;
+    /** Extra request headers merged after validated ones (e.g. Authorization). */
+    extraHeaders?: Record<string, string>;
+};
+/** Loose runtime representation of request options (after serialization). */
+type ResolvedApiRequestOptions = {
+    params?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    body?: unknown;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+};
+/**
+ * Output type produced by a Zod schema, or `unknown` when absent.
+ */
+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 };

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

@@ -0,0 +1,165 @@
+import { ZodType } from 'zod';
+
+/**
+ * Marker used to identify contract objects at runtime (and in the registry).
+ */
+declare const API_CONTRACT_KIND: "api-contract";
+/**
+ * Supported HTTP methods.
+ */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+/**
+ * Splits a string path into its segments at the type level.
+ * `/api/users/:id` -> ['api', 'users', ':id']
+ */
+type SplitPath<TPath extends string> = TPath extends `${infer Head}/${infer Tail}` ? [...SplitPath<Head>, ...SplitPath<Tail>] : TPath extends '' ? [] : [TPath];
+/**
+ * Extracts the path parameter object from a path string.
+ * `/api/posts/:postId/comments/:commentId` -> { postId: string, commentId: string }
+ */
+type PathParams<TPath extends string> = {
+    [Segment in SplitPath<TPath>[number] as Segment extends `:${infer Name}` ? Name : never]: string;
+};
+interface AuthConfig {
+    required?: boolean;
+    roles?: readonly string[];
+    [key: string]: unknown;
+}
+/**
+ * The input accepted by `defineApiContract()`. All schema fields are optional;
+ * generics capture the literal types the user provided.
+ */
+interface ApiContractDefinition<TMethod extends HttpMethod = HttpMethod, TPath extends string = string, TParams extends ZodType | undefined = ZodType | undefined, TQuery extends ZodType | undefined = ZodType | undefined, TBody extends ZodType | undefined = ZodType | undefined, THeaders extends ZodType | undefined = ZodType | undefined, TResponse extends ZodType | undefined = ZodType | undefined> {
+    /** Unique contract name, used by the registry / DevTools / OpenAPI. */
+    name?: string;
+    /** Optional contract version (see roadmap: contract versioning). */
+    version?: number;
+    method: TMethod;
+    path: TPath;
+    /** Path parameters schema, e.g. `z.object({ id: z.string().uuid() })`. */
+    params?: TParams;
+    /** Query parameters schema. */
+    query?: TQuery;
+    /** Request body schema. */
+    body?: TBody;
+    /** Request headers schema (validated against raw header values). */
+    headers?: THeaders;
+    /** Successful response schema. */
+    response?: TResponse;
+    /** Known error payloads keyed by machine-readable error code. */
+    errors?: Record<string, ZodType>;
+    /** OpenAPI summary. */
+    summary?: string;
+    /** OpenAPI description. */
+    description?: string;
+    /** OpenAPI tags. */
+    tags?: readonly string[];
+    /** Marks the endpoint as requiring authentication (informational / extension point). */
+    auth?: boolean | AuthConfig;
+    /** Free-form metadata consumed by tooling (DevTools, mocks, docs). */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A frozen, type-safe API contract — the single source of truth for
+ * runtime validation, TypeScript types, OpenAPI, DevTools and mocks.
+ */
+interface ApiContract<TMethod extends HttpMethod = HttpMethod, TPath extends string = string, TParams extends ZodType | undefined = ZodType | undefined, TQuery extends ZodType | undefined = ZodType | undefined, TBody extends ZodType | undefined = ZodType | undefined, THeaders extends ZodType | undefined = ZodType | undefined, TResponse extends ZodType | undefined = ZodType | undefined> {
+    readonly kind: typeof API_CONTRACT_KIND;
+    readonly method: TMethod;
+    readonly path: TPath;
+    readonly name: string | undefined;
+    readonly version: number | undefined;
+    readonly params: TParams;
+    readonly query: TQuery;
+    readonly body: TBody;
+    readonly headers: THeaders;
+    readonly response: TResponse;
+    readonly errors: Readonly<Record<string, ZodType>> | undefined;
+    readonly summary: string | undefined;
+    readonly description: string | undefined;
+    readonly tags: readonly string[] | undefined;
+    readonly auth: boolean | AuthConfig | undefined;
+    readonly metadata: Readonly<Record<string, unknown>> | undefined;
+}
+/**
+ * Extracts a definition property, defaulting to `undefined` when the key is
+ * absent from the captured (const-inferred) literal type.
+ */
+type PickDefKey<TDef, TKey extends 'params' | 'query' | 'body' | 'headers' | 'response'> = TKey extends keyof TDef ? TDef[TKey] : undefined;
+/**
+ * Maps a definition literal into the resolved contract type.
+ */
+type ContractFromDefinition<TDef extends ApiContractDefinition> = ApiContract<TDef['method'], TDef['path'], PickDefKey<TDef, 'params'>, PickDefKey<TDef, 'query'>, PickDefKey<TDef, 'body'>, PickDefKey<TDef, 'headers'>, PickDefKey<TDef, 'response'>>;
+/**
+ * Input type produced by a Zod schema, or an empty object when absent.
+ */
+type ExtractSchemaInput<T> = T extends ZodType<any, any, infer Input> ? Input : Record<never, never>;
+/**
+ * Any contract, with all generics widened. Used as a variance-friendly bound.
+ */
+type AnyApiContract = ApiContract<HttpMethod, string, ZodType | undefined, ZodType | undefined, ZodType | undefined, ZodType | undefined, ZodType | undefined>;
+type ContractPathParams<C extends AnyApiContract> = C extends {
+    path: infer TPath extends string;
+} ? PathParams<TPath> : Record<never, never>;
+/**
+ * The params the client must send: the intersection of the params schema
+ * input and the parameters extracted from the path itself.
+ */
+type ContractParamsInput<C extends AnyApiContract> = ExtractSchemaInput<C['params']> & ContractPathParams<C>;
+type ContractQueryInput<C extends AnyApiContract> = ExtractSchemaInput<C['query']>;
+type ContractBodyInput<C extends AnyApiContract> = ExtractSchemaInput<C['body']>;
+type ContractHeadersInput<C extends AnyApiContract> = ExtractSchemaInput<C['headers']>;
+/** Response type as returned by handlers (Zod input side). */
+type ContractHandlerResponse<C extends AnyApiContract> = ExtractSchemaInput<C['response']>;
+/** Response type as received by the client (Zod output side). */
+type ContractClientResponse<C extends AnyApiContract> = ExtractSchemaOutput<C['response']>;
+/** Known error codes declared on the contract, plus built-in codes. */
+type ContractErrorCode<C extends AnyApiContract> = (C extends {
+    errors: infer TErrors;
+} ? keyof TErrors & string : never) | 'VALIDATION_ERROR' | 'API_CONTRACT_RESPONSE_VALIDATION_ERROR' | 'INTERNAL_ERROR';
+type MaybePromise<T> = T | Promise<T>;
+type EmptyObject = Record<never, never>;
+type IsEmptyObject<T> = keyof T extends never ? true : false;
+/**
+ * Request options accepted by `useApi` / `useApiClient`.
+ * Requiredness of `params` / `query` / `body` / `headers` is derived from the
+ * contract: an option is required when its schema (or the path) demands it,
+ * and optional (or rejected) otherwise.
+ */
+type ApiRequestOptions<C extends AnyApiContract> = (IsEmptyObject<ContractParamsInput<C>> extends true ? {
+    params?: ContractParamsInput<C>;
+} : {
+    params: ContractParamsInput<C>;
+}) & (undefined extends C['query'] ? {
+    query?: ContractQueryInput<C>;
+} : {
+    query: ContractQueryInput<C>;
+}) & (undefined extends C['body'] ? {
+    body?: ContractBodyInput<C>;
+} : {
+    body: ContractBodyInput<C>;
+}) & (undefined extends C['headers'] ? {
+    headers?: ContractHeadersInput<C>;
+} : {
+    headers: ContractHeadersInput<C>;
+}) & {
+    /** Abort signal forwarded to the underlying fetch. */
+    signal?: AbortSignal;
+    /** Extra request headers merged after validated ones (e.g. Authorization). */
+    extraHeaders?: Record<string, string>;
+};
+/** Loose runtime representation of request options (after serialization). */
+type ResolvedApiRequestOptions = {
+    params?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    body?: unknown;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+};
+/**
+ * Output type produced by a Zod schema, or `unknown` when absent.
+ */
+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 };

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

@@ -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 };