@codexsploitx/schemaapi 1.0.0 → 1.0.2

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.

package/docs/getting_started.md

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

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

package/docs/validation.md

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

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

@@ -1,34 +0,0 @@
-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/rollup.config.js

@@ -1,19 +0,0 @@
-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' }),
-]
-};