@codexsploitx/schemaapi 1.0.1 → 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 CodexSploitx
+
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codexsploitx/schemaapi",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "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

@@ -1,61 +1,70 @@
+<div align="center">
+
 # SchemaApi
 
-> El Zod de las APIs  
-> No reemplaza tu stack. Lo hace confiable.
+**The Zod of APIs**  
+*Type-safe contracts. Runtime validation. Auto-generated docs.*
 
-SchemaApi es una librería de **contratos para APIs**.  
-No sustituye Express, Fastify, Next.js, Axios ni Fetch.  
-Se coloca **encima** de ellos como una capa de validación, coherencia y arquitectura.
+[![npm version](https://img.shields.io/npm/v/schemaapi?style=flat-square&color=blue)](https://www.npmjs.com/package/schemaapi)
+[![License](https://img.shields.io/npm/l/schemaapi?style=flat-square&color=green)](LICENSE)
+[![Tests](https://img.shields.io/github/actions/workflow/status/CodexSploitx/SchemaApi/test.yml?label=tests&style=flat-square)](https://github.com/CodexSploitx/SchemaApi/actions)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
 
----
+[Features](#-features) • [Installation](#-installation) • [Usage](#-usage) • [Adapters](#-adapters) • [Documentation](#-documentation)
 
-## 🧠 Filosofía
+</div>
 
-> “Tu API no es tu código.  
-> Tu API es el contrato que prometes al mundo.”
+---
 
-SchemaApi convierte ese contrato en:
-- Código tipado
-- Validación runtime
-- Seguridad (roles y errores tipados)
-- Documentación (vía CLI y contrato)
-- SDK de cliente básico
-- Tests (unitarios y de contrato)
+## 🚀 Why SchemaApi?
 
----
+**Your API is a contract.** But in most codebases, that contract is broken into pieces:
+- Validation logic in controllers.
+- Types in a `types.ts` file.
+- Documentation in a stale Swagger file.
+- Client SDKs handwritten (and buggy).
 
-## ✅ Lo que hace SchemaApi hoy
+**SchemaApi** unifies everything into a **Single Source of Truth**. Define your contract once, and get everything else for free.
 
-- Valida rutas, métodos HTTP y parámetros
-- Valida query, body y headers
-- Controla roles y autenticación
-- Valida responses y errores (incluye status codes definidos en el contrato)
-- Expone un contrato único fuente de verdad para docs/SDK/tests
-- Ofrece un cliente JS/TS básico vía `createClient`
-- Proporciona una CLI mínima (`schemaapi`) para orquestar generación de docs/SDK/tests
-- Versionado de API con detección de breaking changes
+> "It doesn't replace your framework. It makes it invincible."
 
 ---
 
-## ❌ Lo que NO hace
+## ✨ Features
 
-- No transporta datos (usa Fetch / Axios)
-- No reemplaza tu framework (Express / Next / Fastify)
-- No maneja DB ni ORM
-- No es un servidor
+| Feature | Description |
+| :--- | :--- |
+| **🛡️ End-to-End Type Safety** | Types flow from your server contract directly to your client SDK. No code generation required. |
+| **⚡ Runtime Validation** | Powered by **[Zod](https://zod.dev)**. Automatically validates params, query, body, and headers. |
+| **🔐 Built-in Security** | Define `roles` and `scopes` directly in your contract. RBAC made simple. |
+| **📚 Auto Documentation** | Generate beautiful, interactive HTML documentation that never drifts from code. |
+| **🔌 Framework Agnostic** | Works with Express, Next.js, Fastify, Remix, NestJS, and more. |
+| **📦 Zero-Config SDK** | Export a fully typed client that handles methods, paths, and errors for you. |
 
 ---
 
-## 🌐 Instalación
+## 📦 Installation
 
 ```bash
-npm install schemaapi
-# o
-yarn add schemaapi
+# npm
+npm install schemaapi zod
+
+# pnpm
+pnpm add schemaapi zod
 
+# yarn
+yarn add schemaapi zod
+```
 
-🧩 Ejemplo básico
+---
+
+## 🛠 Usage
+
+### 1️⃣ Define the Contract
 
+Create a shared file (e.g., `contract.ts`). This is your API's law.
+
+```typescript
 import { createContract } from "schemaapi";
 import { z } from "zod";
 
@@ -63,27 +72,95 @@ export const contract = 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()
+        name: z.string(),
+        email: z.string().email(),
       }),
-      errors: { 401: "UNAUTHORIZED", 404: "USER_NOT_FOUND" }
-    }
-  }
+      errors: {
+        404: "USER_NOT_FOUND",
+      },
+    },
+  },
 });
+```
 
+### 2️⃣ Implement the Server
 
+Use the `handle` method to implement the logic. SchemaApi ensures you return exactly what the contract promises.
 
-🛠 Integración con Express
+```typescript
+import express from "express";
+import { contract } from "./contract";
+
+const app = express();
 
 app.get(
   "/users/:id",
-  contract.handle("GET /users/:id", async (ctx) => {
-    const user = await db.findUser(ctx.params.id);
-    return user; // Validación automática
+  contract.handle("GET /users/:id", async ({ params }) => {
+    // `params.id` is strictly typed as a UUID string
+    const user = await db.users.find(params.id);
+
+    if (!user) {
+      throw { status: 404, message: "User not found" };
+    }
+
+    // TypeScript ensures this return value matches the contract
+    return user; 
   })
 );
-# SchemaApi
+```
+
+### 3️⃣ Consume with Client SDK
+
+No more manual fetch calls. No more `any`.
+
+```typescript
+import { createClient } from "schemaapi";
+import { contract } from "./shared/contract";
+
+const client = createClient(contract, { 
+  baseUrl: "https://api.example.com" 
+});
+
+// Full autocomplete & type checking
+const user = await client.users.get({ 
+  id: "550e8400-e29b-41d4-a716-446655440000" 
+});
+
+console.log(user.email); // ✅ Typed!
+```
+
+---
+
+## 🔌 Adapters Ecosystem
+
+SchemaApi is designed to drop into any stack.
+
+| Adapter | Status | Package Support |
+| :--- | :---: | :--- |
+| <img src="https://raw.githubusercontent.com/expressjs/expressjs.com/gh-pages/images/favicon.png" width="20" /> **Express** | ✅ Stable | Native support |
+| <img src="https://assets.vercel.com/image/upload/v1662130559/nextjs/Icon_dark_background.png" width="20" /> **Next.js** | ✅ Stable | API Routes & App Router |
+| <img src="https://raw.githubusercontent.com/fastify/graphics/master/fastify-icon.png" width="20" /> **Fastify** | ✅ Stable | High performance |
+| <img src="https://github.com/remix-run/branding/raw/main/remix-r.png" width="20" /> **Remix** | ✅ Stable | Loaders & Actions |
+| <img src="https://nestjs.com/img/logo-small.svg" width="20" /> **NestJS** | ✅ Stable | Decorators |
+| <img src="https://upload.wikimedia.org/wikipedia/commons/thumb/8/84/Deno.svg/1200px-Deno.svg.png" width="20" /> **Deno** | ✅ Stable | Native HTTP |
+| ⚡ **WebSocket** | 🚧 Beta | Real-time contracts |
+
+---
+
+## 📚 Documentation Generator
+
+Stop writing Swagger files manually. Generate a stunning static documentation site with one command.
+
+```bash
+npx schemaapi generate docs --out ./docs
+```
+
+It creates a fully responsive, dark-mode ready HTML dashboard showing all your routes, schemas, and types.
+
+---
+
+## 📄 License
+
+MIT © [CodexSploitx](https://github.com/CodexSploitx)

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.