@codexsploitx/schemaapi 1.0.1 → 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.1",
+  "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)