nuxt-api-contract 0.1.0

package/dist/composables.d.mts

@@ -0,0 +1,45 @@
+import { AsyncData } from '#app';
+import { AnyApiContract, ApiRequestOptions, ContractClientResponse } from './client.mjs';
+import { ApiError } from './client.mjs';
+import 'zod';
+
+type ContractFetch = (url: string, init: Record<string, unknown>) => Promise<unknown>;
+interface ExecuteRequestContext {
+    /**
+     * Performs the actual fetch. Implemented per environment:
+     * - SSR: internal Nitro `event.$fetch` (no HTTP round-trip).
+     * - Browser: Nuxt `$fetch`.
+     */
+    fetch: ContractFetch;
+}
+
+/**
+ * Executes a contract request and returns the typed response.
+ * Intended for actions, Pinia stores, background jobs and composables where
+ * a reactive `AsyncData` wrapper is not needed. Throws `ApiError` on failure.
+ */
+declare function useApiClient(): Promise<{
+    request: <C extends AnyApiContract>(contract: C, options?: ApiRequestOptions<C>) => Promise<ContractClientResponse<C>>;
+    tryRequest: <C extends AnyApiContract>(contract: C, options?: ApiRequestOptions<C>) => Promise<{
+        data: ContractClientResponse<C>;
+        error: ApiError | null;
+    }>;
+}>;
+/**
+ * Type-safe reactive API composable.
+ *
+ * ```ts
+ * const { data, error, pending, refresh } = await useApi(GetUser, {
+ *   params: { id: userId },
+ * })
+ * ```
+ *
+ * - `data` is typed from the contract's `response` schema.
+ * - Invalid `params` / `query` / `body` are TypeScript errors.
+ * - During SSR the request is routed through Nitro internally (no HTTP hop),
+ *   the payload is transferred to the client, so there is no hydration mismatch.
+ */
+declare function useApi<C extends AnyApiContract>(contract: C, options?: ApiRequestOptions<C>): AsyncData<ContractClientResponse<C>, ApiError>;
+
+export { useApi, useApiClient };
+export type { ExecuteRequestContext };

package/dist/composables.d.ts

@@ -0,0 +1,45 @@
+import { AsyncData } from '#app';
+import { AnyApiContract, ApiRequestOptions, ContractClientResponse } from './client.js';
+import { ApiError } from './client.js';
+import 'zod';
+
+type ContractFetch = (url: string, init: Record<string, unknown>) => Promise<unknown>;
+interface ExecuteRequestContext {
+    /**
+     * Performs the actual fetch. Implemented per environment:
+     * - SSR: internal Nitro `event.$fetch` (no HTTP round-trip).
+     * - Browser: Nuxt `$fetch`.
+     */
+    fetch: ContractFetch;
+}
+
+/**
+ * Executes a contract request and returns the typed response.
+ * Intended for actions, Pinia stores, background jobs and composables where
+ * a reactive `AsyncData` wrapper is not needed. Throws `ApiError` on failure.
+ */
+declare function useApiClient(): Promise<{
+    request: <C extends AnyApiContract>(contract: C, options?: ApiRequestOptions<C>) => Promise<ContractClientResponse<C>>;
+    tryRequest: <C extends AnyApiContract>(contract: C, options?: ApiRequestOptions<C>) => Promise<{
+        data: ContractClientResponse<C>;
+        error: ApiError | null;
+    }>;
+}>;
+/**
+ * Type-safe reactive API composable.
+ *
+ * ```ts
+ * const { data, error, pending, refresh } = await useApi(GetUser, {
+ *   params: { id: userId },
+ * })
+ * ```
+ *
+ * - `data` is typed from the contract's `response` schema.
+ * - Invalid `params` / `query` / `body` are TypeScript errors.
+ * - During SSR the request is routed through Nitro internally (no HTTP hop),
+ *   the payload is transferred to the client, so there is no hydration mismatch.
+ */
+declare function useApi<C extends AnyApiContract>(contract: C, options?: ApiRequestOptions<C>): AsyncData<ContractClientResponse<C>, ApiError>;
+
+export { useApi, useApiClient };
+export type { ExecuteRequestContext };

package/dist/composables.mjs

@@ -0,0 +1,97 @@
+import { useAsyncData, useNuxtApp, useRequestEvent } from '#imports';
+import { f as stableStringify, b as buildRequestPath, s as serializeQuery } from './shared/nuxt-api-contract.QDGSGaVY.mjs';
+import { p as parseApiErrorPayload, A as ApiError, t as toApiError } from './shared/nuxt-api-contract.obS6uV8A.mjs';
+
+function createRequestKey(contract, options) {
+  const { params, query, body, extraHeaders, ...rest } = options ?? {};
+  return [
+    contract.name ?? contract.path,
+    contract.method,
+    contract.path,
+    stableStringify({ params, query, body, extraHeaders, rest })
+  ].join("|");
+}
+function resolveRequestOptions(options) {
+  if (!options) return {};
+  return {
+    params: options.params,
+    query: serializeQuery(options.query),
+    body: options.body,
+    headers: { ...options.headers, ...options.extraHeaders },
+    signal: options.signal
+  };
+}
+function toContractError(error) {
+  const fetchError = error;
+  const payload = fetchError && typeof fetchError === "object" ? parseApiErrorPayload(fetchError.data) : void 0;
+  if (payload) {
+    return new ApiError({
+      code: payload.code,
+      message: payload.message,
+      statusCode: payload.statusCode ?? 500,
+      details: payload.details,
+      issues: payload.issues
+    });
+  }
+  const wrapped = toApiError(error);
+  return new ApiError({
+    code: wrapped.code,
+    message: error instanceof Error ? error.message : wrapped.message,
+    statusCode: error instanceof Error && "statusCode" in error && typeof error.statusCode === "number" ? error.statusCode : 500
+  });
+}
+async function executeContractRequest(contract, options, doFetch) {
+  const resolved = resolveRequestOptions(options);
+  const url = buildRequestPath(contract.path, resolved.params);
+  const hasBodySchema = contract.body !== void 0;
+  const hasBody = resolved.body !== void 0 || hasBodySchema;
+  try {
+    const response = await doFetch(url, {
+      method: contract.method,
+      query: resolved.query,
+      body: contract.method === "GET" || contract.method === "HEAD" ? void 0 : hasBody ? resolved.body ?? {} : void 0,
+      headers: resolved.headers,
+      signal: resolved.signal
+    });
+    return response;
+  } catch (error) {
+    throw toContractError(error);
+  }
+}
+
+async function useApiClient() {
+  const nuxtApp = useNuxtApp();
+  const event = import.meta.server ? useRequestEvent() : void 0;
+  const doFetch = (url, init) => {
+    if (event) {
+      const internalFetch = event.$fetch;
+      return internalFetch(url, init);
+    }
+    return nuxtApp.$fetch(url, init);
+  };
+  return {
+    request: (contract, options) => executeContractRequest(contract, options, doFetch),
+    tryRequest: async (contract, options) => {
+      try {
+        const data = await executeContractRequest(contract, options, doFetch);
+        return { data, error: null };
+      } catch (error) {
+        return { data: void 0, error: toContractError(error) };
+      }
+    }
+  };
+}
+function useApi(contract, options) {
+  const key = createRequestKey(contract, options);
+  const result = useAsyncData(
+    key,
+    async () => {
+      const client = await useApiClient();
+      return client.request(contract, options);
+    },
+    { deep: false, dedupe: "defer" }
+  );
+  return result;
+}
+
+export { useApi, useApiClient };

package/dist/module.d.mts

@@ -0,0 +1,35 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+interface ApiContractModuleOptions {
+    /**
+     * Response validation mode:
+     * - `never`: skip response validation.
+     * - `development` (default): validate outside production builds.
+     * - `always`: validate in every environment.
+     */
+    validateResponse?: 'never' | 'development' | 'always';
+    /** OpenAPI generation (build time) and serving. */
+    openapi?: {
+        enabled?: boolean;
+        /** Route serving the generated document. */
+        path?: string;
+        /** Module exporting contracts (default array or named exports). */
+        entry?: string;
+        title?: string;
+        version?: string;
+        description?: string;
+        output?: string;
+    };
+    /** Enable registered contract mocks (development/testing only). */
+    mocks?: boolean;
+    /** Nuxt DevTools panel (no-op when DevTools is not installed). */
+    devtools?: boolean;
+    /** Directories scanned for contract auto-imports. */
+    contractsDirs?: string[];
+}
+type ModuleOptions = ApiContractModuleOptions;
+type ModuleHooks = Record<string, never>;
+declare const _default: _nuxt_schema.NuxtModule<ApiContractModuleOptions, ApiContractModuleOptions, false>;
+
+export { _default as default };
+export type { ApiContractModuleOptions, ModuleHooks, ModuleOptions };

package/dist/module.d.ts

@@ -0,0 +1,35 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+interface ApiContractModuleOptions {
+    /**
+     * Response validation mode:
+     * - `never`: skip response validation.
+     * - `development` (default): validate outside production builds.
+     * - `always`: validate in every environment.
+     */
+    validateResponse?: 'never' | 'development' | 'always';
+    /** OpenAPI generation (build time) and serving. */
+    openapi?: {
+        enabled?: boolean;
+        /** Route serving the generated document. */
+        path?: string;
+        /** Module exporting contracts (default array or named exports). */
+        entry?: string;
+        title?: string;
+        version?: string;
+        description?: string;
+        output?: string;
+    };
+    /** Enable registered contract mocks (development/testing only). */
+    mocks?: boolean;
+    /** Nuxt DevTools panel (no-op when DevTools is not installed). */
+    devtools?: boolean;
+    /** Directories scanned for contract auto-imports. */
+    contractsDirs?: string[];
+}
+type ModuleOptions = ApiContractModuleOptions;
+type ModuleHooks = Record<string, never>;
+declare const _default: _nuxt_schema.NuxtModule<ApiContractModuleOptions, ApiContractModuleOptions, false>;
+
+export { _default as default };
+export type { ApiContractModuleOptions, ModuleHooks, ModuleOptions };

package/dist/module.mjs

@@ -0,0 +1,145 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { resolve, relative, isAbsolute } from 'node:path';
+import { defineNuxtModule, createResolver, addImports, addServerHandler } from '@nuxt/kit';
+import { defu } from 'defu';
+import { createJiti } from 'jiti';
+import { pickContracts, generateOpenApiDocument } from './openapi.mjs';
+
+function contractRows(contracts) {
+  return contracts.map((contract) => {
+    const params = [...contract.path.matchAll(/:([A-Za-z_][A-Za-z0-9_]*)/g)].map((match) => match[1]);
+    return {
+      label: contract.name ?? "(anonymous)",
+      method: contract.method,
+      path: contract.path,
+      params,
+      tags: contract.tags ?? [],
+      errorCodes: contract.errors ? Object.keys(contract.errors) : []
+    };
+  }).sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method));
+}
+function buildDevtoolsHtml(contracts) {
+  const rows = contractRows(contracts);
+  return JSON.stringify(rows);
+}
+
+const CONFIG_KEY = "apiContract";
+const OPENAPI_DEFAULTS = {
+  enabled: false,
+  path: "/_api-contracts/openapi.json",
+  entry: "contracts/index.ts"
+};
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "nuxt-api-contract",
+    configKey: CONFIG_KEY,
+    compatibility: {
+      nuxt: ">=3.15.0"
+    }
+  },
+  defaults: {
+    validateResponse: "development",
+    openapi: OPENAPI_DEFAULTS,
+    mocks: false,
+    devtools: true,
+    contractsDirs: ["contracts", "server/contracts"]
+  },
+  async setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    const rootDir = nuxt.options.rootDir;
+    nuxt.options.runtimeConfig.apiContract = defu(nuxt.options.runtimeConfig.apiContract ?? {}, {
+      validateResponse: options.validateResponse ?? "development",
+      mocks: options.mocks ?? false
+    });
+    nuxt.options.runtimeConfig.public.apiContract = defu(nuxt.options.runtimeConfig.public.apiContract ?? {}, {
+      mocks: options.mocks ?? false
+    });
+    addImports([
+      { from: "nuxt-api-contract/client", name: "defineApiContract" },
+      { from: "nuxt-api-contract/client", name: "createApiError" },
+      { from: "nuxt-api-contract/client", name: "isApiError" },
+      { from: "nuxt-api-contract/client", name: "mockContract" },
+      { from: "nuxt-api-contract/composables", name: "useApi" },
+      { from: "nuxt-api-contract/composables", name: "useApiClient" },
+      { from: "nuxt-api-contract/server", name: "defineContractHandler" }
+    ]);
+    const hooks = nuxt.hooks;
+    hooks.hook("nitro:config", (nitroConfig) => {
+      nitroConfig.imports = defu(nitroConfig.imports ?? {}, {
+        presets: [
+          {
+            from: "nuxt-api-contract/server",
+            imports: ["defineContractHandler", "createApiError", "defineApiContract"]
+          }
+        ]
+      });
+    });
+    for (const dir of options.contractsDirs ?? []) {
+      const absolute = resolve(rootDir, dir);
+      if (existsSync(absolute)) {
+        nuxt.options.imports.dirs = [...nuxt.options.imports.dirs ?? [], relative(nuxt.options.rootDir, absolute).replaceAll("\\", "/")];
+      }
+    }
+    const openapi = { ...OPENAPI_DEFAULTS, ...options.openapi ?? {} };
+    let contracts = [];
+    const openapiEnabled = openapi.enabled === true;
+    if (openapiEnabled) {
+      const entryPath = isAbsolute(openapi.entry) ? openapi.entry : resolve(rootDir, openapi.entry);
+      if (!existsSync(entryPath)) {
+        console.warn(`[nuxt-api-contract] OpenAPI entry "${openapi.entry}" not found; generation skipped.`);
+      } else {
+        const jiti = createJiti(import.meta.url, { interopDefault: true });
+        const loaded = await jiti.import(entryPath);
+        const values = Array.isArray(loaded) ? [...loaded] : loaded !== null && typeof loaded === "object" ? Object.values(loaded) : [];
+        contracts = pickContracts(values);
+        const { document, warnings } = generateOpenApiDocument(contracts, {
+          title: openapi.title,
+          version: openapi.version,
+          description: openapi.description
+        });
+        for (const warning of warnings) {
+          console.warn(`[nuxt-api-contract] OpenAPI warning (${warning.contract}): ${warning.message}`);
+        }
+        const buildDir = resolve(nuxt.options.buildDir, "api-contracts");
+        mkdirSync(buildDir, { recursive: true });
+        const outputPath = resolve(buildDir, "openapi.mjs");
+        writeFileSync(outputPath, `export const document = ${JSON.stringify(document)}
+`, "utf8");
+        nuxt.options.alias["#api-contracts-openapi"] = outputPath;
+        addServerHandler({
+          route: openapi.path,
+          handler: resolver.resolve("./runtime/server/openapiRoute")
+        });
+      }
+    }
+    if (options.devtools && nuxt.options.dev) {
+      const buildDir = resolve(nuxt.options.buildDir, "api-contracts");
+      mkdirSync(buildDir, { recursive: true });
+      const htmlPath = resolve(buildDir, "devtools.mjs");
+      writeFileSync(htmlPath, `export const html = ${JSON.stringify(buildDevtoolsHtml(contracts))}
+`, "utf8");
+      nuxt.options.alias["#api-contracts-devtools"] = htmlPath;
+      const devtoolsRoute = "/_api-contracts";
+      addServerHandler({
+        route: devtoolsRoute,
+        handler: resolver.resolve("./runtime/server/devtoolsRoute")
+      });
+      try {
+        const devtoolsKitModule = "@nuxt/devtools-kit";
+        const { addCustomTab } = await import(
+          /* @vite-ignore */
+          devtoolsKitModule
+        );
+        addCustomTab({
+          name: "nuxt-api-contract",
+          title: "API Contracts",
+          icon: "carbon:api",
+          view: { type: "iframe", src: devtoolsRoute }
+        });
+      } catch {
+      }
+    }
+  }
+});
+
+export { module$1 as default };

package/dist/openapi.d.mts

@@ -0,0 +1,46 @@
+import { ZodType } from 'zod';
+import { AnyApiContract } from './client.mjs';
+
+/**
+ * OpenAPI generation layer. Completely isolated from runtime validation:
+ * consumes contract objects, produces a JSON-serializable document.
+ *
+ * Unsupported Zod features (transform / refine / superRefine / preprocess)
+ * are represented as closely as possible, a warning is collected and
+ * generation of the whole document never fails.
+ */
+
+type JsonSchemaObject = Record<string, unknown>;
+interface GenerationWarning {
+    contract: string;
+    message: string;
+}
+interface OpenApiOptions {
+    title?: string;
+    version?: string;
+    description?: string;
+}
+interface OpenApiGenerationResult {
+    document: Record<string, unknown>;
+    warnings: GenerationWarning[];
+}
+/** Converts a path like `/api/users/:id` into `/api/users/{id}`. */
+declare function toOpenApiPath(path: string): string;
+/**
+ * Converts a Zod schema into a JSON schema. Best-effort: anything not
+ * directly representable falls back to the inner schema or an empty schema
+ * plus a warning.
+ */
+declare function zodToJsonSchema(schema: ZodType, warnings: GenerationWarning[], contractLabel: string): JsonSchemaObject;
+/** Builds one OpenAPI operation from a contract. */
+declare function contractToOperation(contract: AnyApiContract, warnings: GenerationWarning[]): JsonSchemaObject;
+/**
+ * Generates a complete OpenAPI 3.0 document from contracts.
+ * Never throws: invalid pieces degrade to warnings.
+ */
+declare function generateOpenApiDocument(contracts: AnyApiContract[], options?: OpenApiOptions): OpenApiGenerationResult;
+/** Helper for CLI / tooling: filters a list of unknown values down to contracts. */
+declare function pickContracts(values: unknown[]): AnyApiContract[];
+
+export { contractToOperation, generateOpenApiDocument, pickContracts, toOpenApiPath, zodToJsonSchema };
+export type { GenerationWarning, JsonSchemaObject, OpenApiGenerationResult, OpenApiOptions };

package/dist/openapi.d.ts

@@ -0,0 +1,46 @@
+import { ZodType } from 'zod';
+import { AnyApiContract } from './client.js';
+
+/**
+ * OpenAPI generation layer. Completely isolated from runtime validation:
+ * consumes contract objects, produces a JSON-serializable document.
+ *
+ * Unsupported Zod features (transform / refine / superRefine / preprocess)
+ * are represented as closely as possible, a warning is collected and
+ * generation of the whole document never fails.
+ */
+
+type JsonSchemaObject = Record<string, unknown>;
+interface GenerationWarning {
+    contract: string;
+    message: string;
+}
+interface OpenApiOptions {
+    title?: string;
+    version?: string;
+    description?: string;
+}
+interface OpenApiGenerationResult {
+    document: Record<string, unknown>;
+    warnings: GenerationWarning[];
+}
+/** Converts a path like `/api/users/:id` into `/api/users/{id}`. */
+declare function toOpenApiPath(path: string): string;
+/**
+ * Converts a Zod schema into a JSON schema. Best-effort: anything not
+ * directly representable falls back to the inner schema or an empty schema
+ * plus a warning.
+ */
+declare function zodToJsonSchema(schema: ZodType, warnings: GenerationWarning[], contractLabel: string): JsonSchemaObject;
+/** Builds one OpenAPI operation from a contract. */
+declare function contractToOperation(contract: AnyApiContract, warnings: GenerationWarning[]): JsonSchemaObject;
+/**
+ * Generates a complete OpenAPI 3.0 document from contracts.
+ * Never throws: invalid pieces degrade to warnings.
+ */
+declare function generateOpenApiDocument(contracts: AnyApiContract[], options?: OpenApiOptions): OpenApiGenerationResult;
+/** Helper for CLI / tooling: filters a list of unknown values down to contracts. */
+declare function pickContracts(values: unknown[]): AnyApiContract[];
+
+export { contractToOperation, generateOpenApiDocument, pickContracts, toOpenApiPath, zodToJsonSchema };
+export type { GenerationWarning, JsonSchemaObject, OpenApiGenerationResult, OpenApiOptions };