@codexsploitx/schemaapi 1.0.0

package/docs/adapters/express.md

@@ -0,0 +1,67 @@
+# Express Adapter
+
+Este adaptador permite conectar tu contrato definido con `SchemaApi` a una aplicación Express.
+
+## Uso
+
+```typescript
+import express from "express";
+import { createContract, adapters } from "schemaapi";
+import { z } from "zod";
+
+const app = express();
+app.use(express.json()); // Necesario para parsear body JSON
+
+const contract = createContract({
+  "/users/:id": {
+    GET: {
+      params: z.object({ id: z.string() }),
+      response: z.object({ id: z.string(), name: z.string() }),
+    },
+  },
+});
+
+adapters.express.handleContract(app, contract, {
+  "GET /users/:id": async (ctx) => {
+    // ctx.params, ctx.query, ctx.body, ctx.headers están tipados y validados
+    return { id: ctx.params.id, name: "John Doe" };
+  },
+});
+
+app.listen(3000, () => {
+  console.log("Server running on port 3000");
+});
+```
+
+## Estructura recomendada de contratos
+
+En aplicaciones Express pequeñas puedes definir un único contrato grande, pero a medida que crece el número de endpoints se recomienda separar los contratos por dominio en una carpeta dedicada:
+
+```txt
+contracts/
+ ├─ usersContract.ts
+ ├─ clientsContract.ts
+ ├─ productsContract.ts
+ ├─ facturasContract.ts
+ ├─ ofertasContract.ts
+ └─ index.ts
+```
+
+Cada archivo define el contrato de un dominio concreto y `contracts/index.ts` reexporta todos. Luego puedes montar cada contrato en su propio router o módulo:
+
+```typescript
+import { usersContract } from "./contracts";
+import { adapters } from "schemaapi";
+
+adapters.express.handleContract(app, usersContract, {
+  "GET /users/:id": async (ctx) => {
+    return { id: ctx.params.id, name: "John Doe" };
+  },
+});
+```
+
+## Características
+
+- Validación automática de `params`, `query`, `body` y `headers` usando el esquema Zod.
+- Manejo de errores: Si la validación falla, devuelve automáticamente un error 400.
+- Integración nativa con rutas de Express.

package/docs/adapters/fastify.md

@@ -0,0 +1,64 @@
+# Fastify Adapter
+
+Este adaptador conecta `SchemaApi` con Fastify.
+
+## Uso
+
+```typescript
+import Fastify from "fastify";
+import { createContract, adapters } from "schemaapi";
+import { z } from "zod";
+
+const fastify = Fastify();
+
+const contract = createContract({
+  "/ping": {
+    GET: {
+      response: z.object({ pong: z.boolean() }),
+    },
+  },
+});
+
+adapters.fastify.handleContract(fastify, contract, {
+  "GET /ping": async () => {
+    return { pong: true };
+  },
+});
+
+fastify.listen({ port: 3000 }, (err) => {
+  if (err) throw err;
+  console.log("Server listening on port 3000");
+});
+```
+
+## Estructura recomendada de contratos
+
+Con Fastify es habitual organizar la aplicación en plugins por dominio. Encaja muy bien tener también contratos por dominio en una carpeta dedicada:
+
+```txt
+contracts/
+ ├─ usersContract.ts
+ ├─ clientsContract.ts
+ ├─ productsContract.ts
+ ├─ facturasContract.ts
+ ├─ ofertasContract.ts
+ └─ index.ts
+```
+
+Cada plugin puede registrar solo el contrato que le corresponde:
+
+```typescript
+import { usersContract } from "./contracts";
+import { adapters } from "schemaapi";
+
+adapters.fastify.handleContract(fastify, usersContract, {
+  "GET /users/:id": async (ctx) => {
+    return { id: ctx.params.id };
+  },
+});
+```
+
+## Características
+
+- Usa `fastify.route` internamente.
+- Soporta validación de esquemas (aunque Fastify tiene su propio validador, aquí usamos la validación centralizada de SchemaApi).

package/docs/adapters/hapi.md

@@ -0,0 +1,67 @@
+# Hapi Adapter
+
+Adaptador para el framework Hapi.
+
+## Uso
+
+```typescript
+import Hapi from "@hapi/hapi";
+import { createContract, adapters } from "schemaapi";
+
+const init = async () => {
+  const server = Hapi.server({
+    port: 3000,
+    host: "localhost",
+  });
+
+  const contract = createContract({
+    "/hello/:name": {
+      GET: {
+        // ...
+      },
+    },
+  });
+
+  adapters.hapi.handleContract(server, contract, {
+    "GET /hello/:name": async (ctx) => {
+      return { message: `Hello ${ctx.params.name}` };
+    },
+  });
+
+  await server.start();
+  console.log("Server running on %s", server.info.uri);
+};
+
+init();
+```
+
+## Estructura recomendada de contratos
+
+Hapi anima a agrupar rutas en plugins o dominios funcionales. Para mantener el contrato alineado con esa estructura se recomienda centralizarlo en una carpeta específica:
+
+```txt
+contracts/
+ ├─ usersContract.ts
+ ├─ clientsContract.ts
+ ├─ productsContract.ts
+ ├─ facturasContract.ts
+ ├─ ofertasContract.ts
+ └─ index.ts
+```
+
+Cada plugin puede importar solo el contrato que le corresponde:
+
+```typescript
+import { usersContract } from "./contracts";
+
+adapters.hapi.handleContract(server, usersContract, {
+  "GET /users/:id": async (ctx) => {
+    return { id: ctx.params.id };
+  },
+});
+```
+
+## Características
+
+- Convierte automáticamente las rutas de estilo Express (`:param`) al estilo Hapi (`{param}`).
+- Mapea `request.payload` al body del contexto.

package/docs/adapters/koa.md

@@ -0,0 +1,61 @@
+# Koa Adapter
+
+Adaptador para usar `SchemaApi` con Koa y `koa-router`.
+
+## Uso
+
+```typescript
+import Koa from "koa";
+import Router from "@koa/router"; // o cualquier router compatible
+import bodyParser from "koa-bodyparser";
+import { createContract, adapters } from "schemaapi";
+
+const app = new Koa();
+const router = new Router();
+
+app.use(bodyParser());
+
+const contract = createContract({
+  // ... definición del contrato
+});
+
+adapters.koa.handleContract(router, contract, {
+  // ... implementación de handlers
+});
+
+app.use(router.routes());
+app.use(router.allowedMethods());
+
+app.listen(3000);
+```
+
+## Estructura recomendada de contratos
+
+Koa no impone una estructura de proyecto, pero en aplicaciones medianas/grandes es recomendable separar los contratos por dominio en una carpeta dedicada:
+
+```txt
+contracts/
+ ├─ usersContract.ts
+ ├─ clientsContract.ts
+ ├─ productsContract.ts
+ ├─ facturasContract.ts
+ ├─ ofertasContract.ts
+ └─ index.ts
+```
+
+Luego puedes montar cada contrato en routers separados:
+
+```typescript
+import { usersContract } from "./contracts";
+
+adapters.koa.handleContract(router, usersContract, {
+  "GET /users/:id": async (ctx) => {
+    return { id: ctx.params.id };
+  },
+});
+```
+
+## Requisitos
+
+- Se recomienda usar `koa-bodyparser` o similar para que `ctx.request.body` esté disponible.
+- Se requiere un router que tenga el método `register` (como `@koa/router`).

package/docs/adapters/nest.md

@@ -0,0 +1,66 @@
+# NestJS Adapter
+
+Este adaptador permite integrar `SchemaApi` en una aplicación NestJS existente, registrando las rutas del contrato dinámicamente.
+
+## Uso
+
+En tu archivo principal `main.ts` (o donde inicialices la app):
+
+```typescript
+import { NestFactory } from "@nestjs/core";
+import { AppModule } from "./app.module";
+import { createContract, adapters } from "schemaapi";
+import { z } from "zod";
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+
+  const contract = createContract({
+    "/items": {
+      GET: {
+        response: z.array(z.string()),
+      },
+    },
+  });
+
+  // Registra las rutas del contrato en la aplicación NestJS
+  adapters.nest.SchemaApiModule.register(app, contract, {
+    "GET /items": async () => {
+      return ["item1", "item2"];
+    },
+  });
+
+  await app.listen(3000);
+}
+bootstrap();
+```
+
+## Estructura recomendada de contratos
+
+NestJS suele organizarse por módulos (`UsersModule`, `OrdersModule`, etc.). Es buena práctica acompañar esa estructura con contratos por dominio, por ejemplo:
+
+```txt
+contracts/
+ ├─ usersContract.ts
+ ├─ productsContract.ts
+ ├─ facturasContract.ts
+ └─ index.ts
+```
+
+Cada módulo puede importar únicamente el contrato que le corresponde:
+
+```typescript
+import { usersContract } from "../contracts";
+
+adapters.nest.SchemaApiModule.register(app, usersContract, {
+  "GET /users": async () => {
+    return [];
+  },
+});
+```
+
+## Notas
+
+- Funciona accediendo al adaptador HTTP subyacente de NestJS (Express por defecto).
+- Permite coexistir con controladores tradicionales de NestJS.
+- Ideal para migrar progresivamente o exponer APIs definidas externamente.

package/docs/adapters/next.md

@@ -0,0 +1,66 @@
+# Next.js Adapter
+
+Este adaptador permite usar `SchemaApi` con Next.js App Router (Route Handlers).
+
+## Uso con App Router
+
+Crea un archivo catch-all para tu API, por ejemplo en `app/api/[...route]/route.ts`.
+
+```typescript
+import { createContract, adapters } from "schemaapi";
+import { z } from "zod";
+
+const contract = createContract({
+  "/users/:id": {
+    GET: {
+      params: z.object({ id: z.string() }),
+      response: z.object({ id: z.string() }),
+    },
+  },
+});
+
+const handlers = {
+  "GET /users/:id": async (ctx) => {
+    return { id: ctx.params.id };
+  },
+};
+
+// Exporta los métodos HTTP soportados
+export const { GET, POST, PUT, DELETE, PATCH } = adapters.next.handleContract(
+  contract,
+  handlers
+);
+```
+
+## Estructura recomendada de contratos
+
+En proyectos Next.js es **muy recomendable** definir los contratos en un módulo compartido, separado de los handlers. Por ejemplo:
+
+```txt
+contracts/
+ ├─ usersContract.ts
+ ├─ clientsContract.ts
+ ├─ productsContract.ts
+ ├─ facturasContract.ts
+ ├─ ofertasContract.ts
+ └─ index.ts
+```
+
+Cada archivo exporta un contrato parcial y `contracts/index.ts` reexporta todos. Así puedes usarlo tanto en el servidor (Route Handlers) como en el cliente o en el SDK generado:
+
+```typescript
+import { adapters } from "schemaapi";
+import { usersContract } from "@/contracts";
+
+export const { GET } = adapters.next.handleContract(usersContract, {
+  "GET /users/:id": async (ctx) => {
+    return { id: ctx.params.id };
+  },
+});
+```
+
+## Características
+
+- Soporta App Router (`app/api/...`).
+- Maneja automáticamente `NextRequest` y `NextResponse`.
+- Enrutamiento basado en el contrato (no necesitas crear carpetas para cada ruta si usas catch-all).

package/docs/adapters/remix.md

@@ -0,0 +1,72 @@
+# Remix Adapter
+
+Adaptador para Remix (y React Router v7+). Genera `loader` y `action` tipados para tus rutas.
+
+## Uso
+
+En un archivo de ruta de Remix, por ejemplo `app/routes/users.$id.tsx`:
+
+```typescript
+import { createContract, adapters } from "schemaapi";
+import { useLoaderData } from "@remix-run/react";
+
+// Definición del contrato (idealmente importada de un archivo compartido)
+const contract = createContract({
+  "/users/:id": {
+    GET: {
+      // ...
+    },
+    POST: {
+      // ...
+    },
+  },
+});
+
+const handlers = {
+  "GET /users/:id": async (ctx) => {
+    return { id: ctx.params.id, name: "User Name" };
+  },
+  "POST /users/:id": async (ctx) => {
+    return { success: true };
+  },
+};
+
+// Genera y exporta loader y action
+export const { loader, action } = adapters.remix.createRouteHandlers(
+  contract,
+  handlers,
+  "/users/:id"
+);
+
+export default function UserRoute() {
+  const data = useLoaderData<typeof loader>();
+  return <div>User: {data.name}</div>;
+}
+```
+
+## Estructura recomendada de contratos
+
+En Remix es **muy recomendable** definir los contratos en un módulo compartido (por ejemplo `app/contracts` o un paquete compartido del monorepo), y no dentro de cada archivo de ruta. Por ejemplo:
+
+```txt
+app/
+ ├─ contracts/
+ │   ├─ usersContract.ts
+ │   ├─ productsContract.ts
+ │   └─ index.ts
+ └─ routes/
+     ├─ users.$id.tsx
+     └─ products._index.tsx
+```
+
+De este modo puedes importar el contrato tanto desde el lado servidor (loader/action) como desde el cliente (hooks, componentes) y desde el SDK generado:
+
+```typescript
+import { adapters } from "schemaapi";
+import { usersContract } from "~/contracts";
+```
+
+## Características
+
+- Separa automáticamente `GET` (loader) de otros métodos (action).
+- Usa objetos estándar `Request` / `Response`.

package/docs/cli.md

@@ -0,0 +1,18 @@
+CLI de SchemaApi
+
+La CLI permite generar docs, SDK y tests automáticos desde el contrato.
+
+Comandos básicos
+
+schemaapi generate docs → Genera documentación estilo Swagger.
+
+schemaapi generate sdk → Genera cliente tipado para JS/TS.
+
+schemaapi generate tests → Genera tests automáticos por endpoint.
+
+schemaapi audit → Auditoría de seguridad y validaciones.
+
+Ejemplo
+npx schemaapi generate docs
+npx schemaapi generate sdk
+npx schemaapi generate tests

package/docs/consepts.md

@@ -0,0 +1,18 @@
+Conceptos de SchemaApi
+Filosofía
+
+"Tu API no es tu código. Tu API es un contrato que prometes al mundo."
+
+SchemaApi convierte ese contrato en una capa de validación, documentación, tests y SDK. Todo desde un único lugar.
+
+Contrato: Define rutas, métodos, parámetros, headers, roles, body y responses.
+
+Validación: Garantiza que todas las requests y responses cumplen el contrato.
+
+Seguridad: Controla roles, autenticación y errores.
+
+Documentación: Genera docs automáticamente desde el contrato.
+
+SDK: Crea clientes tipados automáticamente.
+
+Tests: Genera tests para cada endpoint y caso de error.

package/docs/getting_started.md

@@ -0,0 +1,149 @@
+# docs/getting_started.md
+
+# Cómo comenzar con SchemaApi
+
+Este documento explica paso a paso cómo empezar a desarrollar usando SchemaApi, el stack recomendado y la metodología para estructurar tu librería o proyecto.
+
+---
+
+## 1️⃣ Elegir el stack
+
+Para sacar el máximo provecho de SchemaApi y soportar JS y TS:
+
+* **Lenguaje principal:** TypeScript (TS) → permite tipado y autocompletado.
+* **Soporte JS:** Transpila `.ts` a `.js` y distribuye archivos de tipos `.d.ts`.
+* **Node.js:** >=18
+* **Package manager:** npm o pnpm
+* **Test runner:** Vitest o Jest (elige uno para tests unitarios y de integración)
+* **Bundler (opcional):** esbuild o Rollup si quieres empaquetar UMD/CJS/ESM
+* **Linting:** ESLint + Prettier
+
+---
+
+## 2️⃣ Inicializar proyecto
+
+```bash
+mkdir schemaapi-project
+cd schemaapi-project
+npm init -y
+npm install typescript zod
+npm install -D vitest ts-node eslint prettier
+npx tsc --init
+```
+
+Esto crea un proyecto TS básico y prepara el entorno para desarrollo.
+
+---
+
+## 3️⃣ Estructura de carpetas
+
+Organiza el proyecto así:
+
+```
+src/
+  core/          # lógica principal: createContract, validación, context
+  adapters/      # integraciones con Express, Next.js, Fastify, etc.
+  generators/    # docs, SDK, tests automáticos
+  cli/           # scripts de línea de comando
+examples/        # ejemplos de uso
+docs/            # documentación detallada
+types/           # tipos globales para JS
+```
+
+---
+
+## 4️⃣ Comenzar con el contrato básico
+
+1. Crear el contrato con `createContract`.
+2. Definir rutas, métodos, params, body, headers, roles y responses.
+
+```ts
+import { createContract } from "schemaapi";
+import { z } from "zod";
+
+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() }),
+    },
+  },
+});
+```
+
+---
+
+## 5️⃣ Integrar con tu framework
+
+* **Express:** `contract.handle()` para validar requests y responses.
+* **Next.js:** `contract.next()` para Route Handlers.
+* **Fastify / Hono:** middleware adaptado.
+
+```ts
+app.get("/users/:id", contract.handle("GET /users/:id", async (ctx) => {
+  const user = await db.findUser(ctx.params.id);
+  return user;
+}));
+```
+
+---
+
+## 6️⃣ Validar responses y errores
+
+SchemaApi valida responses automáticamente:
+
+* Campos faltantes
+* Tipos incorrectos
+* Status codes
+* Errores definidos
+
+```ts
+return ctx.send(user); // Validación automática de schema
+```
+
+---
+
+## 7️⃣ Generar documentación, SDK y tests
+
+Usa la CLI de SchemaApi:
+
+```bash
+npx schemaapi generate docs   # Documentación tipo Swagger
+npx schemaapi generate sdk    # Cliente tipado JS/TS
+npx schemaapi generate tests  # Tests automáticos por endpoint
+```
+
+---
+
+## 8️⃣ Versionado de contratos
+
+Define versiones de tus contratos y compara cambios:
+
+```ts
+const v1 = createContract({ "/users": { GET: { response: UserSchemaV1 } } });
+const v2 = createContract({ "/users": { GET: { response: UserSchemaV2 } } });
+v2.compareWith(v1); // Detecta breaking changes
+```
+
+---
+
+## 9️⃣ Buenas prácticas
+
+* Siempre define roles y permisos aunque sea público.
+* Usa Zod para validar params, queries y body.
+* Mantén un solo contrato por API principal.
+* Genera docs y SDK desde el contrato, nunca manualmente.
+* Versiona los contratos antes de hacer cambios que rompan compatibilidad.
+* Integra la validación en CI/CD para prevenir errores en producción.
+
+---
+
+## 10️⃣ Próximos pasos
+
+* Integrar observabilidad y metrics
+* Crear tests más avanzados
+* Expandir adapters a más frameworks
+* Implementar auditoría y firewall lógico
+* Construir ejemplos reales de JS/TS y publicar librería en npm

package/docs/sdk.md

@@ -0,0 +1,25 @@
+docs/sdk.md
+SDK de SchemaApi
+
+SchemaApi puede generar clientes tipados que consumen tu API sin escribir axios/fetch manualmente.
+
+Ejemplo de uso
+
+import { createClient } from "schemaapi-sdk";
+
+
+const client = createClient({ baseUrl: "https://api.mysite.com" });
+
+
+const user = await client.users.get({ id: "123" });
+await client.users.update({ id: "123", body: { username: "ferum" } });
+
+Beneficios
+
+Tipado completo en TS
+
+Autocompletado en JS/TS
+
+Consistencia con el contrato
+
+Menos errores en producción