@codexsploitx/schemaapi 1.0.0 → 1.0.2

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.0",
+  "version": "1.0.2",
   "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/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).