@codexsploitx/schemaapi 1.0.0

package/docs/validation.md

@@ -0,0 +1,228 @@
+# SchemaApi - Guía completa de validaciones de Contract
+
+> Esta guía sirve como referencia oficial para crear contratos con SchemaApi.  
+> Incluye ejemplos de errores, manejo de status codes y buenas prácticas.
+
+---
+
+## 1️⃣ Métodos HTTP
+
+SchemaApi valida que:
+
+- El método (GET, POST, PUT, DELETE, PATCH) esté definido en el contrato.
+- No se pueda llamar a rutas inexistentes o métodos no permitidos.
+
+```ts
+"/users/:id": {
+  GET: { ... },
+  POST: { ... }
+}
+Ejemplo de error:
+
+ts
+Copiar código
+// Llamada: DELETE /users/123
+// Contrato no tiene DELETE → SchemaApi lanza error:
+// 405 Method Not Allowed
+2️⃣ Rutas existentes
+Todas las rutas definidas en el contrato son obligatorias.
+
+Los parámetros dinámicos deben declararse en params.
+
+ts
+Copiar código
+"/posts/:postId/comments/:id": {
+  GET: { params: z.object({ postId: z.string(), id: z.string() }) }
+}
+Error típico:
+
+ts
+Copiar código
+// Llamada: GET /posts/123/comments
+// Falta param `id` → 400 Bad Request
+3️⃣ Path Params
+Valida tipos y obligatoriedad con Zod.
+
+Campos incorrectos → 400 Bad Request
+
+ts
+Copiar código
+params: z.object({ id: z.string().uuid() })
+Ejemplo de error:
+
+ts
+Copiar código
+GET /users/abc-not-uuid
+// Error: 400 - "Invalid path param 'id'"
+4️⃣ Query Params
+Validación de query strings.
+
+Soporta opcionales u obligatorios.
+
+ts
+Copiar código
+query: z.object({
+  page: z.number().optional(),
+  limit: z.number().optional()
+})
+Error típico:
+
+ts
+Copiar código
+GET /posts?page=one
+// Error: 400 - "Query param 'page' must be a number"
+5️⃣ Body
+Valida requests POST, PUT, PATCH.
+
+Campos faltantes o tipo incorrecto → 400.
+
+ts
+Copiar código
+body: z.object({
+  username: z.string().min(3),
+  email: z.string().email()
+})
+Errores posibles:
+
+ts
+Copiar código
+POST /users
+body: { username: "ab" } 
+// Error: 400 - "Field 'username' must have at least 3 characters"
+// Error: 400 - "Field 'email' is required"
+6️⃣ Headers
+Valida headers obligatorios y formato.
+
+ts
+Copiar código
+headers: z.object({ authorization: z.string() })
+Errores:
+
+ts
+Copiar código
+// Falta header Authorization
+// Error: 401 Unauthorized
+7️⃣ Roles y autenticación
+Control de permisos por rol.
+
+Roles faltantes → 403 Forbidden
+
+ts
+Copiar código
+roles: ["user", "admin"]
+Ejemplo de error:
+
+ts
+Copiar código
+// Usuario con rol 'guest' intenta GET /users/123
+// Error: 403 Forbidden
+8️⃣ Responses
+Respuesta del handler debe cumplir el schema.
+
+Campos faltantes o adicionales → error en dev/test.
+
+Esto asegura consistencia con SDK y docs.
+
+ts
+Copiar código
+response: z.object({
+  id: z.string(),
+  username: z.string(),
+  email: z.string().email()
+})
+Ejemplo de error:
+
+ts
+Copiar código
+return { id: "123", username: "ferum" }
+// Faltó 'email' → SchemaApi lo detecta
+9️⃣ Status Codes y errores
+Todos los errores posibles se definen en errors.
+
+Si un handler devuelve un status code no definido → error.
+
+ts
+Copiar código
+errors: {
+  401: "UNAUTHORIZED",
+  404: "USER_NOT_FOUND",
+  500: "INTERNAL_ERROR"
+}
+Ejemplo de error:
+
+ts
+Copiar código
+// Handler retorna 418
+// Error: 418 is not defined in contract.errors
+🔟 Consistencia general y breaking changes
+Detecta métodos duplicados, campos obligatorios sin schema.
+
+Versionado de contratos detecta breaking changes automáticamente.
+
+ts
+Copiar código
+const v1 = createContract({ "/users": { GET: { response: UserSchemaV1 } } });
+const v2 = createContract({ "/users": { GET: { response: UserSchemaV2 } } });
+v2.compareWith(v1); // Detecta cambios incompatibles
+1️⃣1️⃣ Ejemplo completo de contrato con todo
+ts
+Copiar código
+import { createContract } from "schemaapi";
+import { z } from "zod";
+
+export const contract = 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"
+      }
+    }
+  }
+});
+✅ Resumen de validaciones
+Capa	Validación
+Método HTTP	✔
+Ruta existente	✔
+Path params	✔
+Query params	✔
+Body	✔
+Headers	✔
+Roles / permisos	✔
+Status code	✔
+Forma de la response	✔
+Errores declarados	✔
+Consistencia general	✔
+Versionado / breaking	✔
+
+💡 Buenas prácticas
+Siempre define roles aunque sea público.
+
+Usa Zod para todos params, queries y body.
+
+Declara todos los errores posibles.
+
+Versiona contratos antes de cambios que rompan compatibilidad.
+
+Integra validación en CI/CD para prevenir errores en producción.
+

package/docs/versioning.md

@@ -0,0 +1,28 @@
+Versionado de SchemaApi
+
+SchemaApi permite definir versiones de contratos y detectar breaking changes automáticamente.
+
+Ejemplo
+const v1 = createContract({ "/users": { GET: { response: UserSchemaV1 } } });
+const v2 = createContract({ "/users": { GET: { response: UserSchemaV2 } } });
+
+
+v2.compareWith(v1); // Detecta cambios incompatibles
+
+Qué detecta
+
+Campos eliminados
+
+Cambios de tipo
+
+Cambios de status code
+
+Eliminación de rutas o métodos
+
+Beneficios
+
+Mantener compatibilidad entre clientes y versiones
+
+Detectar errores antes de desplegar
+
+Facilita migración entre versiones

package/eslint.config.mjs

@@ -0,0 +1,34 @@
+import globals from "globals";
+import pluginJs from "@eslint/js";
+import tseslint from "typescript-eslint";
+import eslintConfigPrettier from "eslint-config-prettier";
+
+export default tseslint.config(
+  {
+    ignores: ["dist/**", "node_modules/**", "coverage/**"],
+  },
+  pluginJs.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    languageOptions: {
+      globals: { ...globals.node, ...globals.browser },
+    },
+  },
+  {
+    files: ["**/*.ts", "**/*.tsx"],
+    languageOptions: {
+      parserOptions: {
+        project: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+  },
+  {
+    files: ["**/*.{js,mjs,cjs}"],
+    ...tseslint.configs.disableTypeChecked,
+    rules: {
+      "@typescript-eslint/no-require-imports": "off",
+    },
+  },
+  eslintConfigPrettier
+);

package/estructure.md

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

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