@codexsploitx/schemaapi 1.0.2 → 1.0.4

package/bin/schemaapi

@@ -249,6 +249,33 @@ function handleInit(adapterArg) {
     fs.writeFileSync(indexPath, 'export * from "./usersContract";\n');
   }
 
+  if (adapter === "next") {
+    const appApiUsersDir = path.join(cwd, "app", "api", "users");
+    if (!fs.existsSync(appApiUsersDir)) {
+      fs.mkdirSync(appApiUsersDir, { recursive: true });
+    }
+    const routePath = path.join(appApiUsersDir, "route.ts");
+    if (!fs.existsSync(routePath)) {
+      const nextRouteContent = [
+        'import { adapters } from "schemaapi";',
+        'import { usersContract } from "../../../contracts";',
+        "",
+        "const handlers = adapters.next.handleContract(usersContract, {",
+        '  "GET /users/:id": async ({ params }) => {',
+        "    return {",
+        "      id: String(params && params.id),",
+        '      name: "John Doe",',
+        "    };",
+        "  },",
+        "});",
+        "",
+        "export const GET = handlers.GET;",
+        "",
+      ].join("\n");
+      fs.writeFileSync(routePath, nextRouteContent);
+    }
+  }
+
   const configPath = path.join(cwd, "schemaapi.config.json");
   let existingConfig = null;
   if (fs.existsSync(configPath)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codexsploitx/schemaapi",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Type-safe API contracts (HTTP/WebSocket) with adapters, client and docs generator.",
   "main": "dist/schemaapi.cjs.js",
   "module": "dist/schemaapi.esm.js",

package/readme.md

@@ -45,6 +45,8 @@
 
 ## 📦 Installation
 
+### Core package
+
 ```bash
 # npm
 npm install schemaapi zod
@@ -56,6 +58,119 @@ pnpm add schemaapi zod
 yarn add schemaapi zod
 ```
 
+### Per-adapter setup
+
+Below are the recommended commands for **new projects** and for **existing projects**.
+
+#### Express
+
+- 🆕 **New project**
+
+```bash
+mkdir my-express-api && cd my-express-api
+npm init -y
+npm install express schemaapi zod
+npx schemaapi init express
+```
+
+- ♻️ **Existing Express project**
+
+```bash
+npm install schemaapi zod
+npx schemaapi init express
+```
+
+#### Next.js
+
+- 🆕 **New project**
+
+```bash
+npx create-next-app@latest my-next-api --ts
+cd my-next-api
+npm install schemaapi zod
+npx schemaapi init next
+```
+
+- ♻️ **Existing Next.js project**
+
+```bash
+npm install schemaapi zod
+npx schemaapi init next
+```
+
+El comando `schemaapi init next` creará automáticamente:
+
+- Carpeta `contracts/` con un contrato de ejemplo `usersContract.ts`.
+- `contracts/index.ts` exportando los contratos.
+- `schemaapi.config.json` apuntando a `contracts/`.
+- Un handler de ejemplo compatible con **App Router** en `app/api/users/route.ts`.
+
+#### Fastify
+
+- 🆕 **New project**
+
+```bash
+mkdir my-fastify-api && cd my-fastify-api
+npm init -y
+npm install fastify schemaapi zod
+npx schemaapi init fastify
+```
+
+- ♻️ **Existing Fastify project**
+
+```bash
+npm install schemaapi zod
+npx schemaapi init fastify
+```
+
+#### Remix
+
+- 🆕 **New project**
+
+```bash
+npx create-remix@latest
+npm install schemaapi zod
+npx schemaapi init remix
+```
+
+- ♻️ **Existing Remix project**
+
+```bash
+npm install schemaapi zod
+npx schemaapi init remix
+```
+
+#### NestJS
+
+- 🆕 **New project**
+
+```bash
+npm i -g @nestjs/cli
+nest new my-nest-api
+cd my-nest-api
+npm install schemaapi zod
+npx schemaapi init nest
+```
+
+- ♻️ **Existing NestJS project**
+
+```bash
+npm install schemaapi zod
+npx schemaapi init nest
+```
+
+#### Deno
+
+- 🆕 / ♻️ **Deno projects**
+
+En Deno no se usa npm para el runtime, pero puedes usar SchemaApi en tu
+tooling o en proyectos que usen `deno2node`. Para Node+Deno híbrido:
+
+```bash
+npm install schemaapi zod
+npx schemaapi init deno
+```
+
 ---
 
 ## 🛠 Usage

package/build.md

@@ -1,246 +0,0 @@
-# Guía de build y publicación de SchemaApi
-
-Este documento resume los pasos para:
-
-- Preparar el paquete para producción
-- Generar el build
-- Verificar que todo está OK
-- Publicar en registries tipo **npm** (y usarlo desde **npm**, **pnpm**, **yarn**, etc.)
-
-> Nota: Los ejemplos asumen que estás en la raíz del repo:  
-> `/Users/admin/Desktop/DEV/SchemaApi`
-
----
-
-## 1. Requisitos previos
-
-- Node.js `>= 18` (ya está definido en `package.json` → `engines.node`).
-- Tener una cuenta en el registry donde quieras publicar (por defecto `https://registry.npmjs.org/`).
-- Tener configurado tu cliente:
-  - Para **npm**:
-    ```bash
-    npm login
-    ```
-  - Para **pnpm**:
-    ```bash
-    pnpm login
-    ```
-  - Para **yarn**:
-    ```bash
-    yarn npm login
-    ```
-
-Todos ellos acaban hablando con el mismo registry (npmjs) salvo que configures otro.
-
----
-
-## 2. Revisar `package.json`
-
-Puntos importantes del `package.json` actual:
-
-- `name`: pon aquí el nombre definitivo del paquete en npm.
-  - Ejemplo: `"name": "schemaapi"` o `"name": "@tu-org/schemaapi"`.
-- Entradas de build ya configuradas:
-  - `"main": "dist/schemaapi.cjs.js"` (CommonJS)
-  - `"module": "dist/schemaapi.esm.js"` (ESM)
-  - `"browser": "dist/schemaapi.umd.js"` (bundle UMD)
-  - `"types": "dist/index.d.ts"` (tipos TypeScript)
-  - `"bin": { "schemaapi": "bin/schemaapi" }` (CLI global)
-- Scripts:
-  - `"build": "rollup -c"`
-  - `"test": "vitest"`
-  - `"lint": "eslint ."`
-
-Antes de publicar:
-
-1. Asegúrate de que `name`, `version`, `description`, `repository`, `author` y `license` son los definitivos.
-2. Si quieres controlar qué ficheros se publican, usa:
-   - Campo `"files"` en `package.json`, o
-   - Un `.npmignore`.
-
----
-
-## 3. Pasos de build y verificación
-
-Desde la raíz del proyecto:
-
-1. Instalar dependencias (si no están ya):
-
-   ```bash
-   npm install
-   # o
-   pnpm install
-   # o
-   yarn install
-   ```
-
-2. Ejecutar los tests:
-
-   ```bash
-   npm test
-   ```
-
-3. Ejecutar el linter (opcional pero recomendado):
-
-   ```bash
-   npm run lint
-   ```
-
-4. Generar el build:
-
-   ```bash
-   npm run build
-   ```
-
-   Esto generará:
-
-   - `dist/schemaapi.cjs.js`
-   - `dist/schemaapi.esm.js`
-   - `dist/schemaapi.umd.js`
-   - `dist/index.d.ts`
-   - `dist/core/...` (tipos intermedios)
-
-5. Validar que el CLI funciona con el build:
-
-   ```bash
-   node bin/schemaapi
-   node bin/schemaapi generate docs
-   ```
-
-   En un proyecto consumidor (fuera de este repo) podrás ejecutar:
-
-   ```bash
-   npx schemaapi generate docs
-   ```
-
----
-
-## 4. Publicar en npm (registry por defecto)
-
-### 4.1. Login
-
-Si no lo has hecho ya:
-
-```bash
-npm login
-```
-
-Introduce usuario, contraseña y email de tu cuenta de npm.
-
-### 4.2. Subir la versión
-
-1. Decide el número de versión siguiendo **semver**:
-   - `1.0.0` → versión inicial estable
-   - `1.0.1` → bugfix
-   - `1.1.0` → nuevas features que no rompen compatibilidad
-   - `2.0.0` → cambios rompientes
-
-2. Actualiza la versión en `package.json` (puedes usar comandos de npm):
-
-   ```bash
-   # Ejemplos:
-   npm version patch   # 1.0.0 -> 1.0.1
-   npm version minor   # 1.0.0 -> 1.1.0
-   npm version major   # 1.0.0 -> 2.0.0
-   ```
-
-   Esto actualiza `package.json` y crea un tag git (si el repo está bajo git).
-
-3. Publicar:
-
-   ```bash
-   npm publish
-   ```
-
-   - Si usas un **scope** público (ej. `@tu-org/schemaapi`), asegúrate de tener `"publishConfig": { "access": "public" }` si es necesario.
-   - Si quieres una etiqueta distinta de `latest`, puedes usar:
-
-     ```bash
-     npm publish --tag next
-     ```
-
----
-
-## 5. Usar el paquete publicado con npm, pnpm, yarn
-
-Una vez publicado en npm, podrás instalarlo desde cualquier cliente:
-
-- Con **npm**:
-
-  ```bash
-  npm install schemaapi
-  # o
-  npm install @tu-org/schemaapi
-  ```
-
-- Con **pnpm**:
-
-  ```bash
-  pnpm add schemaapi
-  # o
-  pnpm add @tu-org/schemaapi
-  ```
-
-- Con **yarn**:
-
-  ```bash
-  yarn add schemaapi
-  # o
-  yarn add @tu-org/schemaapi
-  ```
-
-El contenido publicado (dist, bin, types) será el mismo; solo cambia el cliente que lo descarga.
-
----
-
-## 6. Publicar en otros registries (GitHub Packages, privados, etc.)
-
-El proceso es muy similar; cambia principalmente:
-
-- El `registry` que configuramos.
-- El nombre del paquete (por ejemplo, GitHub Packages suele usar `@OWNER/NAME`).
-
-Ejemplo básico para **GitHub Packages**:
-
-1. En tu `~/.npmrc` o `.npmrc` del proyecto:
-
-   ```ini
-   @tu-org:registry=https://npm.pkg.github.com
-   //npm.pkg.github.com/:_authToken=GITHUB_PERSONAL_ACCESS_TOKEN
-   ```
-
-2. En `package.json`:
-
-   ```json
-   {
-     "name": "@tu-org/schemaapi",
-     "publishConfig": {
-       "registry": "https://npm.pkg.github.com"
-     }
-   }
-   ```
-
-3. Mismo flujo:
-
-   ```bash
-   npm run build
-   npm publish
-   ```
-
----
-
-## 7. Checklist rápido antes de publicar
-
-1. `npm test` pasa.
-2. `npm run build` genera los artefactos en `dist/`.
-3. `node bin/schemaapi` muestra la ayuda sin errores.
-4. `node bin/schemaapi generate docs` funciona en un proyecto de prueba.
-5. `package.json` tiene:
-   - `name` correcto (sin conflictos en el registry).
-   - `version` según semver.
-   - `main`, `module`, `browser`, `types`, `bin` apuntando a `dist/` y `bin/`.
-   - Datos de `repository`, `author`, `license` rellenados.
-6. Has hecho `npm login` (o el login equivalente si usas otro registry).
-
-Con esto deberías tener todo listo para subir la librería a npm y consumirla desde npm/pnpm/yarn como cualquier paquete profesional.
-

package/estructure.md

@@ -1,55 +0,0 @@
-Estructura Recomendada
-
-schemaapi/
-├── src/
-│   ├── core/
-│   │   ├── contract.ts       # createContract y definición de contratos
-│   │   ├── validator.ts      # Validación de requests/responses
-│   │   ├── context.ts        # Contexto de request (params, body, headers)
-│   │   └── response-validator.ts # Validación de respuestas
-│   ├── adapters/
-│   │   ├── express.ts
-│   │   ├── next.ts
-│   │   ├── fastify.ts
-│   │   └── hono.ts
-│   ├── generators/
-│   │   ├── docs.ts           # Generación de documentación
-│   │   ├── sdk.ts            # Generación de SDK tipado
-│   │   └── tests.ts          # Generación de tests automáticos
-│   └── cli/
-│       ├── index.ts
-│       └── commands/
-├── types/
-│   └── index.d.ts             # Tipos globales para JS
-├── docs/
-│   ├── concepts.md
-│   ├── validation.md
-│   ├── cli.md
-│   ├── sdk.md
-│   └── versioning.md
-├── examples/
-│   ├── express-example.ts
-│   ├── nextjs-example.ts
-│   └── client-js.ts
-├── package.json
-├── tsconfig.json
-├── README.md
-└── LICENSE
-
-
-🏗️ Estructura interna
-
-core/ → lógica principal de contratos y validaciones
-
-adapters/ → integración con frameworks
-
-generators/ → docs, SDK y tests automáticos
-
-cli/ → herramientas de línea de comandos
-
-types/ → tipos para JS
-
-
----
-
-

package/libreria.md

@@ -1,319 +0,0 @@
-Plan para crear la librería schemaapi en npm
-1️⃣ Stack y herramientas
-
-Lenguaje: TypeScript (permite generar JS + tipado para usuarios TS)
-
-Bundler: Rollup (para crear el bundle de npm, compatible con Node y Browser)
-
-Target: Node.js y Browser (UMD + ESM)
-
-Testing: Vitest o Jest
-
-Lint / Formato: ESLint + Prettier
-
-Publicación: npm
-
-2️⃣ Estructura del proyecto
-schemaapi/
-├─ src/
-│  ├─ index.ts           # Entry point de la librería
-│  ├─ contract.ts        # createContract
-│  ├─ sdk.ts             # generateSDK
-│  ├─ adapters/          # Adaptadores para Express, Next, Fastify...
-│  │   ├─ express.ts
-│  │   ├─ next.ts
-│  │   └─ fastify.ts
-│  └─ utils/             # Helpers internos
-├─ package.json
-├─ tsconfig.json
-├─ rollup.config.ts
-├─ README.md
-└─ LICENSE
-
-3️⃣ Funcionalidades que debe exponer la librería
-// src/index.ts
-export { createContract } from "./contract";
-export { generateSDK } from "./sdk";
-
-// Adapters (opcional)
-export * as adapters from "./adapters";
-
-
-createContract → define los endpoints y validaciones (params, query, body, headers, roles, response, errores)
-
-generateSDK → genera un SDK tipado listo para usar
-
-adapters → integración rápida con frameworks populares (Express, Next.js, Fastify, NestJS, etc.)
-
-4️⃣ Ejemplo de uso después de publicar en npm
-// Instalación
-npm install schemaapi
-
-// Definir contrato
-import { createContract, generateSDK, adapters } from "schemaapi";
-import { z } from "zod";
-
-const userContract = createContract({
-  "/users/:id": {
-    GET: {
-      params: z.object({ id: z.string().uuid() }),
-      headers: z.object({ authorization: z.string() }),
-      roles: ["user", "admin"],
-      response: z.object({
-        id: z.string(),
-        username: z.string(),
-        email: z.string().email(),
-      }),
-      errors: {
-        401: "UNAUTHORIZED",
-        404: "USER_NOT_FOUND",
-      },
-    },
-  },
-});
-
-// Generar SDK listo para usar
-const schemaApiSdk = generateSDK(userContract, { baseUrl: "http://localhost:3000" });
-
-// Usar en Express
-import express from "express";
-const app = express();
-app.use(express.json());
-adapters.express.handleContract(app, userContract);
-app.listen(3000);
-
-// Usar SDK
-const user = await schemaApiSdk.getUser({ params: { id: "uuid-aqui" }, headers: { authorization: "Bearer TOKEN" } });
-
-5️⃣ Configuración de Rollup
-// rollup.config.ts
-import typescript from "@rollup/plugin-typescript";
-
-export default {
-  input: "src/index.ts",
-  output: [
-    { file: "dist/schemaapi.cjs.js", format: "cjs" },
-    { file: "dist/schemaapi.esm.js", format: "esm" },
-  ],
-  plugins: [typescript({ tsconfig: "./tsconfig.json" })],
-  external: ["zod"], // No incluir dependencias externas
-};
-
-
-Esto permite que tu librería sea usable tanto en Node como en Browser
-
-Usuarios solo hacen import { createContract } from "schemaapi" y listo
-
-6️⃣ Publicación en npm
-npm login
-npm version patch
-npm publish --access public
-
-
-Cada cambio mayor: npm version major
-
-Cada cambio menor: npm version minor
-
-Cada bugfix: npm version patch
-
-7️⃣ Bonus: integración lista para IDE + IA
-
-Todos los métodos de SDK son tipados → autocompletado inmediato
-
-Cada endpoint tiene params/query/body/headers tipados desde el contrato
-
-Adaptadores permiten integración rápida en Express, Next.js, Fastify, NestJS, etc.
-
-Validación de response y errores en tiempo de desarrollo
-
-Si quieres, puedo hacer un prototipo completo de librería lista para publicar en npm, con:
-
-createContract + validaciones completas
-
-generateSDK tipado automáticamente
-
-Adaptadores Express / Next / Fastify
-
-Ejemplos de uso listos para instalar
-
-Rollup + TS configurado para npm
-
-Esto sería básicamente tu librería lista para usar en producción.
-
-¿Quieres que haga eso ahora?
-
-dame el .md para que mi ide trae ia lo haga con todos los adapatores y compatibilidad
-
-¡Perfecto! 😎 Te voy a armar un README.md completo que tu IDE con IA pueda usar para autocompletar y generar todo: contratos, SDK, y adaptadores listos para todos los frameworks populares. Todo explicado paso a paso y con ejemplos.
-
-# SchemaApi - Librería NPM: Contratos, SDK y Adaptadores
-
-> Guía completa de uso de SchemaApi con todos los adaptadores y compatibilidad para frameworks populares.  
-> Diseñado para autocompletado y soporte de IDEs con IA.
-
----
-
-## 1️⃣ Instalación
-
-```bash
-npm install schemaapi zod
-
-
-zod es la dependencia principal para la validación de schemas.
-
-2️⃣ Importación principal
-import { createContract, generateSDK, adapters } from "schemaapi";
-import { z } from "zod";
-
-
-createContract: define tus endpoints y validaciones
-
-generateSDK: genera un SDK tipado listo para usar
-
-adapters: integración rápida con frameworks populares
-
-3️⃣ Crear un contrato de ejemplo
-export const userContract = createContract({
-  "/users/:id": {
-    GET: {
-      params: z.object({ id: z.string().uuid() }),
-      query: z.object({ includePosts: z.boolean().optional() }),
-      headers: z.object({ authorization: z.string() }),
-      roles: ["user", "admin"],
-      response: z.object({
-        id: z.string(),
-        username: z.string(),
-        email: z.string().email(),
-      }),
-      errors: {
-        401: "UNAUTHORIZED",
-        404: "USER_NOT_FOUND",
-      },
-    },
-    PUT: {
-      params: z.object({ id: z.string().uuid() }),
-      body: z.object({ username: z.string().min(3) }),
-      roles: ["admin"],
-      response: z.object({ success: z.literal(true) }),
-      errors: {
-        401: "UNAUTHORIZED",
-        403: "FORBIDDEN",
-      },
-    },
-  },
-});
-
-4️⃣ Generar el SDK
-export const schemaApiSdk = generateSDK(userContract, {
-  baseUrl: "http://localhost:3000",
-});
-
-
-Todos los endpoints del contrato se convierten en métodos tipados
-
-Incluye validación automática de params, query, body, headers y response
-
-Ejemplo de uso del SDK:
-
-const user = await schemaApiSdk.getUser({
-  params: { id: "uuid-aqui" },
-  query: { includePosts: true },
-  headers: { authorization: "Bearer TOKEN" },
-});
-console.log(user.username);
-
-5️⃣ Adaptadores para frameworks populares
-5.1 Express
-import express from "express";
-const app = express();
-app.use(express.json());
-adapters.express.handleContract(app, userContract);
-app.listen(3000);
-
-5.2 Next.js API Routes
-// pages/api/users/[id].ts
-export default adapters.next.handleContract(userContract);
-
-5.3 Fastify
-import Fastify from "fastify";
-const fastify = Fastify({ logger: true });
-adapters.fastify.handleContract(fastify, userContract);
-fastify.listen({ port: 3000 });
-
-5.4 NestJS
-import { Module } from "@nestjs/common";
-
-@Module({
-  imports: [
-    adapters.nest.SchemaApiModule.register({ contracts: [userContract] }),
-  ],
-})
-export class AppModule {}
-
-5.5 Koa
-import Koa from "koa";
-import bodyParser from "koa-bodyparser";
-const app = new Koa();
-app.use(bodyParser());
-adapters.koa.handleContract(app, userContract);
-app.listen(3000);
-
-5.6 Hapi
-import Hapi from "@hapi/hapi";
-const server = Hapi.server({ port: 3000 });
-await adapters.hapi.handleContract(server, userContract);
-await server.start();
-
-5.7 Remix
-// app/routes/users.$id.ts
-export const loader = adapters.remix.handleContract(userContract);
-export const action = adapters.remix.handleContract(userContract);
-
-5.8 Bun / Deno
-import { serve } from "bun";
-serve(adapters.deno.handleContract(userContract), { port: 3000 });
-
-6️⃣ Ejemplo completo de frontend usando SDK
-import { schemaApiSdk } from "../sdk";
-
-async function loadUser(id: string) {
-  try {
-    const user = await schemaApiSdk.getUser({
-      params: { id },
-      query: { includePosts: true },
-      headers: { authorization: "Bearer TOKEN" },
-    });
-    console.log(user.username, user.email);
-  } catch (err) {
-    console.error("Error:", err.message);
-  }
-}
-
-
-Compatible con React, Next.js o cualquier frontend
-
-Tipado y autocompletado garantizado
-
-7️⃣ Beneficios
-
-Una sola fuente de verdad (contract) para todos los frameworks
-
-Validación completa: params, query, body, headers, roles, response, status codes
-
-SDK tipado listo para backend y frontend
-
-Compatible con IDEs IA → autocompletado y prevención de errores
-
-Fácil integración con Express, Next.js, Fastify, NestJS, Koa, Hapi, Remix, Bun, Deno
-
-8️⃣ Tips para IDE con IA
-
-Mantener todos los contratos en un archivo central contracts/index.ts
-
-Siempre usar TypeScript para tipado completo
-
-Documentar cada endpoint para que la IA sugiera tipos y errores automáticamente
-
-Usar schemaApiSdk para llamadas reales en frontend o backend
-
-Cambios en el contrato → regenerar SDK → autocompletado actualizado

package/resumen.md

@@ -1,188 +0,0 @@
-# SchemaApi - Checklist de Validaciones de Contract
-
-> Guía completa y oficial de todas las validaciones que SchemaApi realiza sobre tus contratos de API.  
-> Ideal como checklist de desarrollo, QA o documentación interna.
-
----
-
-## 1️⃣ Validaciones de método y ruta
-
-| Validación | Descripción | Error típico |
-|------------|------------|-------------|
-| Método HTTP permitido | GET, POST, PUT, DELETE, PATCH, OPTIONS… | 405 Method Not Allowed |
-| Existencia de la ruta | La ruta debe estar definida en el contrato | 404 Not Found |
-| Parámetros dinámicos | `:id`, `:slug`, `*` deben declararse en `params` | 400 Bad Request |
-| Métodos duplicados | Evita definir GET/POST duplicados en la misma ruta | Error en build/dev |
-| Jerarquía de rutas | Rutas anidadas deben respetar la jerarquía | Error en build/dev |
-| Versionado de rutas | Detecta breaking changes entre versiones | Warning/Error |
-
----
-
-## 2️⃣ Validaciones de Path Params
-
-| Validación | Descripción | Error típico |
-|------------|------------|-------------|
-| Tipo correcto | string, number, UUID, regex, enums | 400 Bad Request |
-| Obligatorio/Optional | Parámetros marcados obligatorios deben llegar | 400 Bad Request |
-| Formato | Regex, longitud mínima/máxima | 400 Bad Request |
-
-**Ejemplo:**
-
-```ts
-params: z.object({ id: z.string().uuid() })
-3️⃣ Validaciones de Query Params
-Validación	Descripción	Error típico
-Tipos correctos	number, string, boolean, arrays	400 Bad Request
-Obligatorio / Opcional	Define si es requerido	400 Bad Request
-Valores por defecto	Permite fallback si no llega	Correcto
-Combinaciones dependientes	Ej: sort + order	400 Bad Request
-Arrays y objetos anidados	Valida estructura compleja	400 Bad Request
-
-4️⃣ Validaciones de Body
-Validación	Descripción	Error típico
-Body obligatorio	Según método HTTP	400 Bad Request
-Campos obligatorios / opcionales	Deben cumplir schema	400 Bad Request
-Tipos de campos	string, number, boolean, array, objeto	400 Bad Request
-Valores por defecto	Permite fallback	Correcto
-Estructuras anidadas	Arrays y objetos complejos	400 Bad Request
-Validaciones avanzadas	Regex, min/max, custom validator	400 Bad Request
-
-5️⃣ Validaciones de Headers
-Validación	Descripción	Error típico
-Headers obligatorios	Ej: Authorization, Content-Type	401/403
-Tipos y formato	string, number, regex	400/401
-Valores predeterminados	Si no llega header opcional	Correcto
-Combinaciones de headers	Ej: X-Role + Authorization	400/403
-
-6️⃣ Roles y Autenticación
-Validación	Descripción	Error típico
-Rol requerido	Endpoint solo accesible a roles definidos	403 Forbidden
-Múltiples roles	Permite más de un rol	Correcto
-Rol predeterminado	Optional fallback	Correcto
-Integración JWT / sesiones	Opcional, validación token	401/403
-Scopes / permisos adicionales	Validación más granular	403 Forbidden
-
-7️⃣ Responses y Status Codes
-Validación	Descripción	Error típico
-Schema de respuesta	Debe cumplir schema exacto	Error dev/test
-Campos faltantes / extra	Validación estricta	Error dev/test
-Status codes válidos	Solo los definidos en errors	Error dev/test
-Arrays / objetos anidados	Validación completa	Error dev/test
-Generación SDK / docs	Automática a partir del schema	N/A
-Response opcional 204	Para métodos sin body	Correcto
-
-8️⃣ Errores y excepciones
-Validación	Descripción	Error típico
-Todos los errores declarados	Cada status code debe estar definido	Error dev/test
-Status code no definido	Handler retorna status no declarado	Error dev/test
-Mensajes consistentes	String o códigos	Warning/Error
-Custom error handlers	Opcional, consistente	Correcto
-Errores globales	Soporte de fallback	Correcto
-
-9️⃣ Validaciones avanzadas / opcionales
-Validación	Descripción	Error típico
-Consistencia general	Sin duplicados, campos obligatorios definidos	Warning/Error
-Comparación de versiones	Detecta breaking changes	Warning/Error
-Validación condicional	requiredIf / dependencias	400 Bad Request
-Validación cross-endpoint	Relaciones entre rutas	Warning/Error
-Observabilidad	Logs automáticos de fallos	N/A
-Rate limiting lógico	Throttling opcional	429 Too Many Requests
-Payload / performance	Tamaño máximo, response time	413 Payload Too Large
-
-🔟 Meta-validaciones y herramientas
-Validación	Descripción
-Generación documentación	Swagger / OpenAPI / Markdown
-Generación SDK	JS / TS tipado automático
-Generación tests	Unitarios por endpoint y errores
-Compatibilidad versiones	Detecta breaking changes entre versiones
-Seguridad básica	Validación headers sensibles / inyección
-
-✅ Resumen conceptual
-SchemaApi puede validar todo lo que pueda romper la consistencia o confiabilidad de tu API:
-
-Desde lo más básico (método, ruta, params, body)
-
-Hasta avanzado (roles, versionado, dependencias cross-endpoint)
-
-Esto convierte tu librería en una capa de contrato potente, que asegura que la API siempre se use de forma correcta antes de tocar la red o base de datos.
-
-
-# SchemaApi - Flujo de Validación de Contract
-
-> Diagrama visual del flujo completo de validaciones en SchemaApi.  
-> Muestra qué se valida en cada capa antes de ejecutar un endpoint.
-
----
-
-## Flujo de Validación
-
-```mermaid
-flowchart TD
-    A[Inicio: Llamada API] --> B{Ruta existe?}
-    B -- No --> C[404 Not Found]
-    B -- Sí --> D{Método HTTP permitido?}
-    D -- No --> E[405 Method Not Allowed]
-    D -- Sí --> F{Path Params válidos?}
-    F -- No --> G[400 Bad Request - Invalid Path Param]
-    F -- Sí --> H{Query Params válidos?}
-    H -- No --> I[400 Bad Request - Invalid Query Param]
-    H -- Sí --> J{Body válido?}
-    J -- No --> K[400 Bad Request - Invalid Body]
-    J -- Sí --> L{Headers válidos?}
-    L -- No --> M[401/403 - Invalid Headers]
-    L -- Sí --> N{Rol autorizado?}
-    N -- No --> O[403 Forbidden]
-    N -- Sí --> P[Ejecutar Handler]
-    P --> Q{Response cumple schema?}
-    Q -- No --> R[Error Dev/Test - Invalid Response]
-    Q -- Sí --> S{Status Code permitido?}
-    S -- No --> T[Error Dev/Test - Status Code No Definido]
-    S -- Sí --> U[Respuesta exitosa al cliente]
-🔹 Descripción del flujo
-Ruta existe: Verifica que la ruta solicitada esté definida en el contrato.
-
-Método HTTP permitido: Solo se aceptan los métodos definidos (GET, POST, etc.).
-
-Path Params: Validación de tipos y obligatoriedad.
-
-Query Params: Validación de tipos, opcionales/obligatorios y combinaciones.
-
-Body: Validación de estructura, tipos, campos obligatorios y avanzados (regex, min/max, arrays/objetos).
-
-Headers: Obligatorios y formato correcto.
-
-Roles / permisos: Usuario debe tener rol autorizado.
-
-Ejecutar Handler: Si todo es válido, se ejecuta la función del endpoint.
-
-Response: Debe cumplir el schema exacto definido.
-
-Status Code: Debe estar declarado en errors si no es 2xx.
-
-Salida: La respuesta final al cliente es 100% validada.
-
-🔹 Tipos de errores detectados
-Error	Capa	Código típico
-Ruta no existe	Ruta	404
-Método no permitido	Método	405
-Path Param inválido	Path Params	400
-Query Param inválido	Query Params	400
-Body inválido	Body	400
-Headers inválidos	Headers	401 / 403
-Rol no autorizado	Roles	403
-Response inválida	Response	Dev/Test Error
-Status code no declarado	Status	Dev/Test Error
-
-🔹 Beneficios de este flujo
-Detecta errores antes de que lleguen a producción
-
-Garantiza consistencia de contratos
-
-Permite SDK tipado y generación de documentación automática
-
-Facilita QA y testing: cada error es predecible y controlado
-
-Posibilita versionado y detección de breaking changes
-
-💡 Tip visual:
-Puedes integrar este diagrama con herramientas como Mermaid.js en docs, para que sea interactivo y siempre actualizado según tu contrato.