@codexsploitx/schemaapi 1.0.0 → 1.0.1

package/package.json

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

package/docs/adapters/deno.md

@@ -1,51 +0,0 @@
-# Deno Adapter
-
-Adaptador para usar `SchemaApi` en Deno (usando `Deno.serve`).
-
-## Uso
-
-```typescript
-import { createContract, adapters } from "npm:schemaapi"; // Asumiendo importación desde npm o path relativo
-
-const contract = createContract({
-  "/api/data": {
-    GET: {
-      // ...
-    },
-  },
-});
-
-const handler = adapters.deno.handleContract(contract, {
-  "GET /api/data": async (ctx) => {
-    return { data: "Hello form Deno" };
-  },
-});
-
-Deno.serve(handler);
-```
-
-## Estructura recomendada de contratos
-
-Cuando usas Deno (o entornos similares como Workers, Bun, etc.) es habitual compartir contratos entre varias funciones/lambdas y entre servidor y cliente. Es **muy recomendable** centralizar los contratos en una carpeta o paquete dedicado:
-
-```txt
-contracts/
- ├─ usersContract.ts
- ├─ clientsContract.ts
- ├─ productsContract.ts
- ├─ facturasContract.ts
- ├─ ofertasContract.ts
- └─ index.ts
-```
-
-Cada handler puede importar solo el contrato que necesita:
-
-```typescript
-import { adapters } from "npm:schemaapi";
-import { usersContract } from "./contracts/usersContract.ts";
-```
-
-## Características
-
-- Usa la API estándar de Web (`Request`, `Response`).
-- Compatible con cualquier entorno que use `(req: Request) => Response`, incluyendo Bun, Cloudflare Workers, etc.

package/docs/adapters/express.md

@@ -1,67 +0,0 @@
-# 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

@@ -1,64 +0,0 @@
-# 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

@@ -1,67 +0,0 @@
-# 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

@@ -1,61 +0,0 @@
-# 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

@@ -1,66 +0,0 @@
-# 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

@@ -1,66 +0,0 @@
-# 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

@@ -1,72 +0,0 @@
-# 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

@@ -1,18 +0,0 @@
-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

@@ -1,18 +0,0 @@
-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.