@codexsploitx/schemaapi 1.0.0

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@codexsploitx/schemaapi",
+  "version": "1.0.0",
+  "description": "Type-safe API contracts (HTTP/WebSocket) with adapters, client and docs generator.",
+  "main": "dist/schemaapi.cjs.js",
+  "module": "dist/schemaapi.esm.js",
+  "browser": "dist/schemaapi.umd.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "schemaapi": "bin/schemaapi"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "rollup -c",
+    "dev": "echo 'Agrega Vite más adelante para dev rápido'",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "test": "vitest"
+  },
+  "keywords": [
+    "api",
+    "schema",
+    "zod",
+    "http",
+    "websocket",
+    "typescript"
+  ],
+  "author": "codexsploitx",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CodexSploitx/SchemaApi.git"
+  },
+  "license": "ISC",
+  "type": "commonjs",
+  "dependencies": {
+    "@types/ws": "^8.18.1",
+    "tslib": "^2.8.1",
+    "ws": "^8.19.0",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@rollup/plugin-commonjs": "^29.0.0",
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@types/jest": "^30.0.0",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.0.0",
+    "prettier": "^3.8.0",
+    "rollup": "^4.55.1",
+    "supertest": "^7.2.2",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.53.0",
+    "vitest": "^4.0.17"
+  }
+}

package/readme.md

@@ -0,0 +1,89 @@
+# SchemaApi
+
+> El Zod de las APIs  
+> No reemplaza tu stack. Lo hace confiable.
+
+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.
+
+---
+
+## 🧠 Filosofía
+
+> “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)
+
+---
+
+## ✅ Lo que hace SchemaApi hoy
+
+- 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
+
+---
+
+## ❌ Lo que NO hace
+
+- No transporta datos (usa Fetch / Axios)
+- No reemplaza tu framework (Express / Next / Fastify)
+- No maneja DB ni ORM
+- No es un servidor
+
+---
+
+## 🌐 Instalación
+
+```bash
+npm install schemaapi
+# o
+yarn add schemaapi
+
+
+🧩 Ejemplo básico
+
+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(),
+        email: z.string().email()
+      }),
+      errors: { 401: "UNAUTHORIZED", 404: "USER_NOT_FOUND" }
+    }
+  }
+});
+
+
+
+🛠 Integración con 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
+  })
+);
+# SchemaApi

package/resumen.md

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

package/rollup.config.js

@@ -0,0 +1,19 @@
+const typescript = require('@rollup/plugin-typescript');
+const { nodeResolve } = require('@rollup/plugin-node-resolve');
+const commonjs = require('@rollup/plugin-commonjs');
+const pkg = require('./package.json');
+
+module.exports = {
+  input: 'src/index.ts',
+  output: [
+    { file: pkg.main, format: 'cjs', sourcemap: true },
+    { file: pkg.module, format: 'esm', sourcemap: true },
+    { file: pkg.browser, format: 'umd', name: 'SchemaApi', sourcemap: true }
+  ],
+  external: ['zod'],
+plugins: [
+  nodeResolve(),
+  commonjs(),
+  typescript({ tsconfig: './tsconfig.json', declaration: true, rootDir: 'src', outDir: 'dist' }),
+]
+};

package/src/adapters/deno.ts

@@ -0,0 +1,139 @@
+import type { createContract } from "../core/contract";
+import { buildErrorPayload } from "../core/contract";
+
+type AnyContract = ReturnType<typeof createContract>;
+
+type MethodSchemaLike = {
+  media?: {
+    kind?: string;
+    contentTypes?: string[];
+    maxSize?: number;
+  };
+};
+
+type DownloadResult =
+  | {
+      data: unknown;
+      contentType?: string;
+      filename?: string;
+    }
+  | unknown;
+
+export function handleContract(
+  contract: AnyContract,
+  handlers: Record<
+    string,
+    (ctx: Record<string, unknown>) => unknown | Promise<unknown>
+  >
+) {
+  // Retorna una función (req: Request) => Promise<Response> compatible con Deno.serve
+  return async (req: Request): Promise<Response> => {
+    const url = new URL(req.url);
+    const path = url.pathname;
+    const method = req.method;
+
+    const schema = contract.schema as Record<string, Record<string, unknown>>;
+
+    for (const routePattern of Object.keys(schema)) {
+      // Regex simple para matching: /users/:id -> /users/([^/]+)
+      // Agregamos ^ y $ para match exacto
+      const regexPattern = routePattern.replace(/:[a-zA-Z0-9_]+/g, "([^/]+)");
+      const regex = new RegExp(`^${regexPattern}$`);
+
+      const match = path.match(regex);
+      if (match) {
+        const routeMethods = schema[routePattern] as Record<
+          string,
+          unknown
+        >;
+        if (routeMethods[method]) {
+          const endpoint = `${method} ${routePattern}`;
+          const implementation = handlers[endpoint];
+          const methodSchema =
+            (routeMethods as Record<string, unknown>)[method] as MethodSchemaLike | undefined;
+
+          if (!implementation) {
+            return new Response("Not Implemented", { status: 501 });
+          }
+
+          // Extraer params
+          // Necesitamos saber los nombres de los parámetros para mapearlos
+          // routePattern: /users/:id/posts/:postId
+          // match: [..., "123", "456"]
+          const paramNames = (routePattern.match(/:[a-zA-Z0-9_]+/g) || []).map(
+            (p) => p.substring(1)
+          );
+          const params: Record<string, string> = {};
+          paramNames.forEach((name, index) => {
+            params[name] = match[index + 1];
+          });
+
+          const wrapped = contract.handle(endpoint, implementation);
+
+          try {
+            let body = undefined;
+            if (method !== "GET" && method !== "HEAD") {
+              try {
+                body = await req.json();
+              } catch {}
+            }
+
+            const context = {
+              params,
+              query: Object.fromEntries(url.searchParams.entries()),
+              body,
+              headers: Object.fromEntries(req.headers.entries()),
+            };
+
+            const result = await wrapped(context);
+            const media = methodSchema?.media;
+            if (media && media.kind === "download") {
+              const download = result as DownloadResult;
+              const data =
+                download &&
+                typeof download === "object" &&
+                "data" in download
+                  ? (download as { data: unknown }).data
+                  : download;
+              const contentType =
+                download &&
+                typeof download === "object" &&
+                "contentType" in download
+                  ? (download as { contentType: string }).contentType
+                  : "application/octet-stream";
+              const filename =
+                download &&
+                typeof download === "object" &&
+                "filename" in download
+                  ? (download as { filename: string }).filename
+                  : undefined;
+
+              const headers: Record<string, string> = {
+                "Content-Type": String(contentType),
+              };
+              if (filename) {
+                headers["Content-Disposition"] = `attachment; filename="${filename}"`;
+              }
+
+              return new Response(data as BodyInit, {
+                headers,
+              });
+            }
+
+            return new Response(JSON.stringify(result), {
+              headers: { "Content-Type": "application/json" },
+            });
+          } catch (err: unknown) {
+            const payload = buildErrorPayload(err);
+            return new Response(JSON.stringify(payload), {
+              status: payload.status,
+              headers: { "Content-Type": "application/json" },
+            });
+          }
+        }
+      }
+    }
+
+    return new Response("Not Found", { status: 404 });
+  };
+}

package/src/adapters/express.ts

@@ -0,0 +1,134 @@
+import type { createContract } from "../core/contract";
+
+type AnyContract = ReturnType<typeof createContract>;
+
+type MethodSchemaLike = {
+  media?: {
+    kind?: string;
+    contentTypes?: string[];
+    maxSize?: number;
+  };
+};
+
+type DownloadResult =
+  | {
+      data: unknown;
+      contentType?: string;
+      filename?: string;
+    }
+  | unknown;
+
+export interface ExpressLikeRequest {
+  params: Record<string, string>;
+  query: Record<string, string>;
+  body: unknown;
+  headers: Record<string, string>;
+  user?: unknown;
+  [key: string]: unknown;
+}
+
+export interface ExpressLikeResponse {
+  json: (body: unknown) => void;
+  send?: (body: unknown) => void;
+  setHeader?: (name: string, value: string) => void;
+}
+
+export type ExpressLikeHandler = (
+  req: ExpressLikeRequest,
+  res: ExpressLikeResponse,
+  next: (err?: unknown) => void
+) => void | Promise<void>;
+
+export type ExpressLikeApp = {
+  [method: string]: (path: string, handler: ExpressLikeHandler) => void;
+};
+
+export function handleContract(
+  app: ExpressLikeApp,
+  contract: AnyContract,
+  handlers: Record<
+    string,
+    (ctx: Record<string, unknown>) => unknown | Promise<unknown>
+  >
+) {
+  const schema = contract.schema as Record<string, Record<string, unknown>>;
+
+  Object.keys(schema).forEach((route) => {
+    const methods = schema[route] as Record<string, unknown>;
+
+    Object.keys(methods).forEach((method) => {
+      const endpoint = `${method} ${route}`;
+      const implementation = handlers[endpoint];
+      const methodSchema = (methods as Record<string, unknown>)[
+        method
+      ] as MethodSchemaLike | undefined;
+
+      if (!implementation) {
+        return;
+      }
+
+      const wrapped = contract.handle(endpoint, implementation);
+      const httpMethod = method.toLowerCase();
+      const register = (app as Record<string, unknown>)[
+        httpMethod
+      ] as ExpressLikeApp[keyof ExpressLikeApp] | undefined;
+
+      if (!register) {
+        return;
+      }
+
+      register(route, async (req, res, next) => {
+        try {
+          const context: Record<string, unknown> = {
+            params: req.params || {},
+            query: req.query || {},
+            body: req.body,
+            headers: req.headers || {},
+            user: req.user,
+          };
+
+          const result = await wrapped(context);
+          const media = methodSchema?.media;
+          if (media && media.kind === "download") {
+            const download = result as DownloadResult;
+            const data =
+              download &&
+              typeof download === "object" &&
+              "data" in download
+                ? (download as { data: unknown }).data
+                : download;
+            const contentType =
+              download &&
+              typeof download === "object" &&
+              "contentType" in download
+                ? (download as { contentType: string }).contentType
+                : "application/octet-stream";
+            const filename =
+              download &&
+              typeof download === "object" &&
+              "filename" in download
+                ? (download as { filename: string }).filename
+                : undefined;
+
+            if (typeof res.setHeader === "function") {
+              res.setHeader("Content-Type", contentType);
+              if (filename) {
+                res.setHeader(
+                  "Content-Disposition",
+                  `attachment; filename="${filename}"`
+                );
+              }
+            }
+            if (typeof res.send === "function") {
+              res.send(data);
+              return;
+            }
+          }
+          res.json(result);
+        } catch (error) {
+          next(error);
+        }
+      });
+    });
+  });
+}